README-SPHINX.md

Using Sphinx and GitHub pages.

You can use Sphinx output for GitHub pages but you have to defeat GitHub Pages' built-in behaviour first as it attempts to build documentation. You don't need it to do that as Sphinx does that nicely. All you want is to have GitHub host the pages generated by Sphinx.

1. Put documentation source in /docs/source

2. Ensure documentation is published to somewhere like /docs/build/html

3. Add an empty .nojekyll to /docs

4. Put an index.html in /docs that simply redirects to the Sphinx documentation. That file should just contain:

   <meta http-equiv="refresh" content="0; url=./build/html/index.html" />

5. Build the documentation from the /docs directory with ./make-docs.sh (which simply executes sphinx-build -b html source build/html)

6. Commit and push the documentation, including the build directory and its files

7. Enable GitHub Pages in GitHub using the Master Branch with docs option

That's it!

Keeping a fork synchronised

If you have forked this repository remember to keep it synchronised if you want to keep up-to-date. With a fresh clone of the fork you can accomplish this using the following command sequence: -

$ git remote add upstream https://github.com/InformaticsMatters/okd-orchestrator.git
$ git fetch upstream
$ git merge upstream/master

See GitHub's help on the topic in its Syncing a fork page.

---