forget about Wiki?

[rob-vh]

There are too many deficiencies with gollum (github's version of Wiki), in combination with sphinx.

• sphinx does not generate a _Sidebar.md, you have to rename the index.md into _Sidebar.md
• gollum doesn't accept .md filetypes in URIs, you have to add a sphinx global option to kill those in the generated md flies
• gollum does not respect directories (folders) in the URI of links, so the source directory with autodoc files results in 404 errors from the _Sidebar, meaning, you would have to edit _Sidebar.md anyway
• there is only 1 Wiki link that is branch independent
• you have to maintain a separate git and do a separate push to update the Wiki
• a summary

Advantage of Wiki? Ehrm, it displays all of the docs contents, where github's interpretation of rst files is lacking (doesn't support table from file, doesn't interpret the autodoc directives).

So, lets

1. rename the _build directory to build,
2. build md files after any change using make markdown,
3. git add docs/build/markdown/* (including ./source)
4. put a link to docs/build/markdown/index.md into README.md
5. deactivate Wiki
6. Bob's your uncle

This works, except...

1. Make sure the .md filetype is present in the URI of all links
2. selecting the link from README, you are dumped into Preview mode, with the navigator as a sidebar, and no fancy sidebar.
3. somehow, the one single screenshot in Installation results in 404. That's because Installation.md looks for _static/file.png, whereas the file really is in ../_static/file.png

Still, it does provide a manual for the working branches.

[rob-vh]

Or skip the md files altogether, and publish the HTML output from sphinx:

1. rename the _build directory to build,
2. build HTML files after any change using make html
3. git add docs/build/html/* (including ./source)
4. put a link to docs/build/html/index.html into README.md
5. deactivate Wiki

Except: when you add the link into README.md, it shows you the raw file. The only way I found to publish HTMLis via gh-pages, and this only shows the pages for 1 branch.

[rob-vh]

If we want to stick with Wiki, we could ensure the .md files are all in a single flat directory. If we move the pyracf.rst and modules.rst files from docs/source to docs (by changing the parameters of the api-doc command), sphinx would create the output in the right directory, and keeps the URI flat too. Then all that's needed is rename index.md into _Sidebar.md before updating the wiki repo.