Sphinx

notes on using sphinx

github

notes on specifically integrating sphinx with github:

https://daler.github.io/sphinxdoc-test/includeme.html

step 1: setup

mkdir myrepo
cd myrepo
git init
touch README
git add README
git commit -m 'first commit'
git remote add origin git@github.com:someone/myrepo.git
git push origin master

step 2: set up sphinx

Continuing from the commands above, from the myrepo directory, we create a sphinx docs directory:

mkdir docs/
cd docs/
sphinx-quickstart

These defaults are confusing and there's not much explanation of what they mean. It's a bit frustrating. I guess I'll just blindly accept defaults like a trained monkey.

step 3: check out local copy of gh-pages

Now we need to have a local copy of the gh-pages branch of our repo, which is where we will put content we want to publish.

We do the following:

• Create a new, empty, orphan branch called gh-pages
• Populate the orphan branch with static content (html/javascript/css), which is automatically hosted by github at myusername.github.io/myreponame
• In the master branch of the repo, clone a local copy of the repo's gh-pages branch. this is the folder where sphinx will generate its final html content.
• You will not put this final output folder (the cloned copy of the gh-pages branch) under version control... not necessary.

We start where the commands above left off, so we are in the folder myrepo.

Start by creating an empty, orphan branch called gh-pages:

git branch --orphan gh-pages 

Note that we are also not going to check this folder into the repo. It's basically a way to symbolically link the sphinx output dir and the live-hosted gh-pages branch. (We use the same pattern with Pelican.)

BUILDDIR      = build