Going Further into Sphinx¶
Automatic build with travis¶
Travis CI is a continuous integration service used to build and test software projects hosted at GitHub (Wikipedia).
Add a .travis.yml
file to the top level directory of your GitHub
repository with instructions how to build and test your software:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | language: python
branches:
only:
- master
python:
- "2.7"
sudo: false
install:
- pip install -r requirements.txt
- pip install -r requirements-dev.txt
- python setup.py install
script:
- py.test -v giza
- cd docs; make html linkcheck
|
Add the instruction to build your Sphinx documentation with the
linkcheck
target. The travis build will be run (in a docker
container) each time you push to GitHub. When somethings fails
(install, tests, docs, linkcheck) then travis will inform the person
who made the last commit via eMail.
You can add an image with a link to the status of the travis build to your documenation:
.. image:: https://travis-ci.org/my-orga/my-repo.svg?branch=master
:target: https://travis-ci.org/my-orga/my-repo
:alt: Travis Build
Configure theme for rtd¶
$ pip install sphinx_rtd_theme
Or:
$ conda install sphinx_rtd_theme
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
html_theme = 'default'
else: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
on_rtd
is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
Use Sphinx for GitHub Pages¶
Include the extension githubpages:
extensions = ['sphinx.ext.githubpages']
This extension creates .nojekyll file on generated HTML directory to publish the document on GitHub Pages.
See also: http://gisellezeno.com/tutorials/sphinx-for-python-documentation.html