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.
Related
I want to update Topic/page titles on my GitHub wiki (which is currently using Markdown syntax). When I do that using the GUI it renames the Markdown files, and breaks all of the links.
I know that I can rename the Topic files in the Git repository and push the changes, but that doesn't help the broken links.
Is there a way to avoid this, and make GitHub Wiki's behave more like other Wiki products? I could not find an better way on GitHub documentation.
Welcome to StackOverflow. As best I can determine you cannot rename a GitHub Wiki page without its markdown file also being updated to the new name. The two are tightly coupled.
This Web Applications (StackExchange) Question has some alternatives you may consider, i.e. instead of renaming the page, create a copy. Then edit the original page so that it directs visitors to the new page via a link. This way the original page link remains valid but directs visitors to the new page.
Azure DevOps includes a Wiki feature for all projects. The wiki content is stored as a git repository, with a .md markdown file for every page. You can clone the repository and look at how it is organised. All pages in the wiki allow users to submit comments - clearly these must be stored somewhere, but where? They do not appear in the wiki repository.
Unfortunately, we haven't sort it into any history and it only relevant to Wiki page until now. This comment feature is being implement but haven't supported from UI.
As of today, what we provide is view the comments content from UI, or get them from API:
Get https://dev.azure.com/{org name}/{project name}/_apis/wiki/wikis/{wiki name}/pages/{page id}/comments
In fact, the backend data structure has been built, but we haven't provide the corresponding UI to public. So, with above api, you can not only get the comments you want, but also record the modification history of the comments.
Personally, it sounds a good idea about putting comments into source control since it not only records some important conversation about current wiki, also has representation about its development process.
Much recommend you can share your idea here, it is the official forum that our Product Group reviewed.
You can share the suggestion ticket link here, I'm sure I would be the first voter on that. Also, there will have other SO users who view this ticket support that.
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
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.
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