Authoring on GitHub Wiki
Developers on Subutai Projects use the GitHub Wiki to quickly add documentation for other developers and for users. The Wiki's of projects host important information useful to everyone and we need to make it all searchable and part of the entire Subutai Documentation set with RTD. Besides this the documentation system also helps to organize the GitHub Wiki.
The GitHub Wiki has a feature where the following files if present effect how the documentation looks:
- _Sidebar.md offers a sidebar that can be used to organize the Wiki documents into a hierarchy
- _Footer.md this is used to generate a footer at the bottom of every page
- _Header.md as the name suggests is used to generate a header at the top of every page
The documentation system will automatically generate a _Sidebar.md file when it runs and commit it to the wiki repositories. It uses a PARENT_PATH attribute in an HTML comment at the end of each Wiki Markdown file to determine how to organize the documentation for you. As an example take a look at the Subutai Agent Wiki. Some of the pages are under an expandable CLI folder on the sidebar. The CLI command Markdown files in the wiki contain the following at the end of the file:
<!--
PARENT_PATH: /CLI
ORIGIN: github
-->
The PARENT_PATH attribute categorizes wiki pages into a tree. The root of the tree / can also be used. In that case, the files are put at the top level. This is the case for some of the documents in the Agent Wiki. Authors should use this marker to categorize their pages to better organize their respective project wikis. If you do NOT have this attribute specified the documentation system put's the Wiki page under an /Uncategorized section.
The RTD site uses this organization to place your documents appropriately in the right sections and make them expandable. The hierarchy you use on the GitHub Wiki is maintained in the Subutai Documentation generated.
Here's how the Agent Project's GitHub Wiki sections appear in the generated RTD site:
Just like in Google Docs using headings properly is important. Garbage in garbage out.
Although nothing specific is needed from GitHub Wiki markdown page authors other than common sense to organize their page headings correctly, the system does a few things that authors should be aware of. Before generating restructuredText from a Markdown page, the name of the file is used to generate a title header. The dashes for spaces that are used by the GitHub Wiki are replaced with spaces to generate the title. So please think twice when creating the page because it becomes the title which is displayed in the table of contents for the project.
There seems to be a lot of prefixes being used like [Automation] etc to make up for the fact that people just did not know about the sidebar feature for organizing issues. This should be removed and the proper PARENT_PATH set to organize the documentation from now on.