Documentation versioning for GitHub projects - github

What is the recommended approach on GitHub to organizing documentation when working on a new version that represents a major rewrite?
In my project pg-promise I rely on jsDoc to generate all the documentation, and then publish it into gh-pages, as one usually does.
And while working on a new version that's a major rewrite and a documentation change, what is the best approach to making the new/unreleased documentation available? -
1. Should I simply create a separate repository just for the sake of publishing updated documentation there?
2. Should I use an external hosting/solution altogether?
3. Is there any GitHub feature that will let me publish more than one documentation version?
Thanks in advance!


This is feasible using Github Actions along with a static site generator (SSG) of your choice such as VuePress, Gatsby, Jekyll etc.
In its simplest form, create a GH action to generate the static site folder of the branch/release, then push the folder to corresponding folder in the branch pointed to by GH pages, say gh-pages. One of the branches/releases should be pushed to root. GitHub Pages Deploy Action can be helpful. Add a dropdown list of versions to your static website pointing to the matching folder.
Example:
GitHub action
dropdown list implemented by Vue component
rendered site powered by GH pages

Related

How to Automatically Generate Documentation for ReadMe's from Multiple Repositories

I want to automatically generate a documentation site that contains the ReadMe's from all the repositories within my project. I am a little new to GitHub, so I'm not sure if my terminology is correct. I provide the link to the GitHub page that has all of the repositories.
https://github.com/casework
I was wondering if there is any way to have a website that automatically generates documentation for all the ReadMe's found in any of the repositories. Ideally, this would be a website that recognizes if the ReadMe's were edited or if a new repository was made, and then automatically update the documentation for the website.
I have been looking at mkdocs and Sphinx, but I was wondering if there was an easy way to automatically generate and update documentation based on the ReadMe's from these repositories. As far as I know, these tools would not automatically update the website.

How do I create a "Revision page" with the GitHub API?

I would like to create a "Revision page" where the people can see on what I've been working using GitHub there's an example about what I mean:
It is supposed to show the commits from my GitHub repository.

A) More information is required
Firstly, could you clarify if it is your intention to
Show the Commit history for a single repository, or
You wish to show your commit activity across multiple repositories
Also:
You wish to have this information displayed on Github, or
You
wish to have this information displayed on an external site.
B) Displaying information on GitHub
If the intention is a combination of 1 and 3, then my first suggestion would be to check the existing functionality of GitHub, which has such a feature built-in.
This can be accessed by navigating to your repository, and simply clicking the Commits button. An example of the results can be found here:
Example GitHub Commit History
C) Displaying information on an external site
As you mention that you have limited experience with PHP, I would certainly start by evaluating GitList:
GitList allows you to browse repositories using your favorite browser,
viewing files under different revisions, commit history and diffs.
GitList is free and open source software, written in PHP, on top of
Silex and the Twig template engine.
If you feel confident that you could create your own solution to display the information in an external web page, then you should begin by familiarising yourself with the GitHub Developer Documentation, and specifically:
List commits on a repository
It is also worth examining the following article and existing GitHub project in order to enhance your knowledge:
How to Use Github’s API with PHP (SitePòint Article with code)
GitHub PHP Client (GitHub Project)
It may be that you can clone one of these projects, strip it down to the features essential for your needs, and customise the UI.

Make Jira links clickable in Github

Is there a way I can make Jira ticket id's on Github link to Jira? (much the same way as how it happens on Bitbucket).
Maybe there is a plugin or something I could use ?
EDIT:
I specifically want ticket id's in Github to link through to Jira, this is not described in any of the resources below:
How do I connect github to JIRA?
https://confluence.atlassian.com/display/BITBUCKET/Linking+Bitbucket+and+GitHub+accounts+to+JIRA
https://help.github.com/articles/integrating-jira-with-your-projects/

Update 2022:
Dusan Plavak mentions in the comments that, as of today (Q1 2022), you can also import / automate creation of autolinks via github api.
You can also use gh api:
gh api repos/octocat/hello-world/autolinks \
-f -q 'key_prefix:key_prefix url_template:url_template'
And since July 2022, you also have autolinks with alphanumeric IDs (for instance for a Trello card URL: https://trello.com/c/3eZr2Bxw).
2019: No need for Chrome plugin, Safari hack or scripts.
From October 2019, GitHub can automatically transform TICKET references to Jira links, for example.
See "Save time linking resources with autolink references" from Lars Schneider.
Now you can set up an autolink reference and GitHub will automatically create links (to external systems) for you.
How it works
If you use GitHub with external services (like Jira), you might be familiar with shorthand references (like TICKET-123) to point to resources in those external systems.
Starting today, GitHub can automatically transform shorthand references into clickable links for GitHub Pro, Team, and Enterprise plans.
So not the regular github.com.
To enable this feature, a repository admin needs to register the reference prefix (such as TICKET-) in the settings.
Afterwards, references of that type are detected in issues, pull requests, comments, or commit messages, and turned into links.
This speeds up navigation between GitHub and external systems.
See documentation.
Note that the ticket prefix is not included in the hyperlink despite being included in the anchor text. The URL preview in the setting is accurate:
The animation in the feature announcement, replicated above, shows this limitation but not clearly.
This means that you have to either include the project key in the target URL as well or prefix all project keys with a another key and use that as the autolink prefix.
You cannot even use Git's trailers to reference tickets and use autolinks, because trailers are key-value pairs separated by : (colon space) and an autolink prefix that ends with a space is invalid.

I decided to make a Chrome extension for this ! This extension works on all websites, not just Jira ! :D
Install it here:
https://chrome.google.com/webstore/detail/jira-hotlinker/lbifpcpomdegljfpfhgfcjdabbeallhk
Source code:
https://github.com/helmus/Jira-Hot-Linker

If you mean the commit message for commit e0d9e32 shows TEST-1234 Fixed this really bad bug and you want TEST-1234 to link to http://www.your-jira.com/browse/TEST-1234 then no it does not look like this is possible.
You could look to do a Chrome/Firefox browser plugin that accomplishes the behavior you desire. (Scans the webpage looking in certain sections for JIRA Key's and then updates them to links)

I wrote a site specific Safari hack. It requires you to install it yourself, but that gives you the opportunity to read the code (it's short!) first. https://github.com/unicode-org/icu-jira-safari
it fetches elements of class commit, gh-header-title, and js-issue-row with getElementsByClassName()
then, for anything such as ICU-1234 (our Jira project id), it creates a link to the appropriate URL on the Jira server.
I wanted to include Jira issue status as well, but Atlassian Cloud CORS settings prevent that.
Here is an example if the linkification (ICU-10464 turns into a link on the right hand side).

Someone made exactly what I wanted coming from gitlab.
https://chrome.google.com/webstore/detail/linkify-jira-issues/ekbbnaokafbanjgmcbllligemhiclbcb
This updates the text in my github PRs to convert them in clickable links.

I made a super simple Chrome extension for this. It simply adds a link to the relevant JIRA ticket on your Github pull request page in a non-obtrusive way (See screenshot below)
Install it here: https://chrome.google.com/webstore/detail/github-to-jira/dhnagjladcclacjnccpnibdmkljidnhl?hl=en-GB
Source code here: https://github.com/mfalade/github-to-jira
While Github Autolink is an awesome solution, this is easier to use for the following reasons.
You don't need to provide a description with ticket number for this to work. It automatically derives ticket number from your branch name.
You don't have to configure anything on the Github admin page. Perfect for users who don't have admin privileges
You can work on multiple projects or teams more easily. Supports multiple ticket prefixes.
This extension works for all project management tools you might want to link to

Github:documents about github pages

Is there any document about the whole process of building my blog with github pages?I have read the official introduction,but less help.

There are two different ways to create a GitHub page:
Create a repo called YOUR_USERNAME.github.io
Create a branch called gh-pages on a standard repo
Later, you must put some HTML files and commit. You will see the page running. You can also use Jekyll which has a template engine but it's a bit hard to start with it.

How to generate a website from GitHub wiki pages

I've used GitHub pages to generate a beautiful website for my project (this one). Now I want to keep the documentation of my project up to date, and having everything in a single README.md file is probably not scalable to the many features we are adding.
So, I thought that the best place to keep the documentation is the GitHub wiki, but I'd like to integrate the wiki to the gh-pages generated site, keeping the beautiful layout.
How would I take the GitHub wiki and generate an HTML web site with a customizable layout?

Here is an example URL for a wiki:
https://github.com/golang/go/wiki
On the same page you will find a clone link:
https://github.com/golang/go.wiki.git
Then run the Markdown files through Hugo or even create a new repository
to the host site based on the Wiki.

You could include your wiki as subtree.
BTW, GitHub Pages now no longer need the gh-pages branch. Create a repository named your-user-name.github.io; it will automatic generate to a website. See GitHub Pages for more detail.