Create a developer documentation with sphinx and github

Introduction

When developing a software, it is necessary to have a place to share and put documentation. For users, this documentation must be nice and easy to read. It must allow to search specific topics. For developers, this documentation must be easy to write, easy to read and browse and keep history. It is also important that documentation facilitate link to real code, for example by providing syntax highlighting or extraction of code’s documentation.

We choose to use sphinx to edit and build documentation and github to share it and keep history. Please have look to Sphinx page and github page for more information.

All tips and models are based on excellent work done by IPython Team . Parts of this documentation directly come from IPython-doc and IPython-website.

Create official organization website

If you just want to contribute, please go to next step. This step is useful for organization owners only.

Create source repository

  • Generate a github project called “organization-website” with organization account, not with your user account. This project contains documentation sources (mainly sphinx rst files)
  • Prepare github directory :
git clone https://github.com/ORGANIZATION/ORGANIZATION-website
cd ORGANIZATION-website
mkdir _scripts
  • Copy scripts gh-pages.py and copy_trees.py into “_scripts” directory
  • Modify _scripts/gh-pages.py and change page_repo values. Generally, just replace ORGANIZATION and USERNAME.
  • Create your sphinx project with sphinx-wizard
sphinx-quickstart

# To question "Separate source and build directories (y/n) [n]", answer n
# To question "Generate Makefile (y/n) [y]", answer n

Create html repository

Create repository to put generated html files.

  • create one repository for your user or organization as explained in Github help pages.
    • Normally, just replace “-website” by ”.github.io”.
  • create a file named ”.nojekyll” in project myorganization.github.io this is required to
    • disable jekyll (and allow to put folder beginning with _, see Github faq)
    • create a master branch necessary to build scripts

Create your personal repositories

Warning

Then, on a terminal, do

# Checkout your fork

git clone https://github.com/USERNAME/ORGANIZATION-website
cd ORGANIZATION-website


# Create an empty branch used to host generated files
# Never work on this branch as script will replace all files automatically

git checkout --orphan gh-pages
git rm -rf . # clear branch
touch README.md
touch .nojekyll
git add README.md .nojekyll
git commit -m "Initial commit"
git push origin gh-pages


# Come back to source directory
git checkout master

Standard workflow

Local Editing

While your documentation has not reached a stable step :

  • modify rst sources, add files, ...
  • generate html files locally with “make html”
  • fix warnings and errors
  • check and fix links with “make linkcheck”
  • check and fix doctests mith “make doctest”
  • check result in _build/html/index.html

Share your work

When your modifications are enough stable, you may want to share your work with other

  • remove “_build” and “gh-pages” directory and do all checks again (links, doctests, errors and warnings)
  • Commit and push source modifications : see github workflow
  • generate html files and an associated commit with “make gh-pages”
  • check git state in gh-pages (normally all is ok)
  • push gh-pages

Publish your work on official website

Now, other developers can see sources on your fork and result at http://USERNAME.github.io/ORGANIZATION-website

If your work is accepted, you may want to integrate your work in official website. For this last step, id depends on workflow your team has chosen.

Generally, if you are a maintainer of official website, you can push html files to website with

cd ORGANIZATION-website
# Remove all pages
#rm -rf gh-pages
make publish

If you are a contributor, just create a pull-request following standard git workflow.