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.

If you already have a gh-pages branch, run:

git clone -b gh-pages https://github.com/someuser/myrepo.git _build/html

Otherwise, if you need to create the gh-pages brach, start by cloning a copy of the repo into a folder called html:

git clone https://github.com/someuser/myrepo.git _build/html

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.)

Now create a gh-pages branch that does not share any history with the master branch:

cd _build/html
git checkout --orphan gh-pages

# be careful!
rm -rf *

echo "<h1>hello world</h1>" > index.html
git add index.html
git commit index.html -m 'initial commit of gh-pages branch'
git push origin gh-pages

step 4: test run

Make the HTML documentation files:

make html

This should tell you that the files are in _build/html. This will create new HTML content in the staging area for the gh-pages branch. You should be able to see what has changed using git:

cd _build/html
git status .

To add everything:

git add -A .
git commit -a -m 'Adding everything!'