sphinx / doc / devguide.rst

Sphinx Developer's Guide

Abstract

This document describes the development process of Sphinx, a documentation system used by developers to document systems used by other developers to develop other systems that may also be documented using Sphinx.

The Sphinx source code is managed using Mercurial and is hosted on BitBucket.

hg clone https://bitbucket.org/birkenfeld/sphinx

Community

sphinx-users <sphinx-users@googlegroups.com>
Mailing list for user support.
sphinx-dev <sphinx-dev@googlegroups.com>
Mailing list for development related discussions.
#pocoo on irc.freenode.net

IRC channel for development questions and user support.

This channel is shared with other Pocoo projects. Archived logs are available here.

Bug Reports and Feature Requests

If you have encountered a problem with Sphinx or have an idea for a new feature, please submit it to the issue tracker on BitBucket or discuss it on the sphinx-dev mailing list.

For bug reports, please include the output produced during the build process and also the log file Sphinx creates after it encounters an un-handled exception. The location of this file should be shown towards the end of the error message.

Including or providing a link to the source files involved may help us fix the issue. If possible, try to create a minimal project that produces the error and post that instead.

Contributing to Sphinx

The recommended way to contribute code to Sphinx is to fork the Mercurial repository on BitBucket and then submit a pull request after committing your changes.

These are the basic steps needed to start developing.

  1. Create an account on BitBucket.

  2. Fork the main Sphinx repository (birkenfeld/sphinx) using the BitBucket interface.

  3. Clone the forked repository to your machine.

    hg clone https://bitbucket.org/USERNAME/sphinx-fork
    cd sphinx-fork
    
  4. Checkout the appropriate branch.

    For changes that should be included in the next minor release (namely bug fixes), use the stable branch.

    hg checkout stable
    

    For new features or other substantial changes that should wait until the next major release, use the default branch.

  5. Setup your Python environment.

    virtualenv ~/sphinxenv
    . ~/sphinxenv/bin/activate
    pip install -e .
    
  6. Hack, hack, hack.

    For tips on working with the code, see the Coding Guide.

  7. Test, test, test.

    Run the unit tests:

    pip install nose
    make test
    

    Build the documentation and check the output for different builders:

    cd docs
    make clean html text man info latexpdf
    

    Run the unit tests under different Python environments using :program:`tox`:

    pip install tox
    tox -v
    

    Add a new unit test in the tests directory if you can.

    For bug fixes, first add a test that fails without your changes and passes after they are applied.

  8. Commit your changes.

    hg commit -m 'Add useful new feature that does this.'
    

    BitBucket recognizes certain phrases that can be used to automatically update the issue tracker.

    For example:

    hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
    

    would close issue #42.

  9. Push changes to your forked repo on BitBucket.

    hg push
    
  10. Submit a pull request from your repo to birkenfeld/sphinx using the BitBucket interface.

Coding Guide

  • Try to use the same code style as used in the rest of the project. See the Pocoo Styleguide for more information.
  • For non-trivial changes, please update the :file:`CHANGES` file. If your changes alter existing behavior, please document this.
  • New features should be documented. Include examples and use cases where appropriate. If possible, include a sample that is displayed in the generated output.
  • When adding a new configuration variable, be sure to document it and update :file:`sphinx/quickstart.py`.
  • Use the included :program:`utils/check_sources.py` script to check for common formatting issues (trailing whitespace, lengthy lines, etc).

Debugging Tips

  • Delete the build cache before building documents if you make changes in the code by running the command make clean or using the :option:`sphinx-build -E` option.
  • Use the :option:`sphinx-build -P` option to run Pdb on exceptions.
  • Use node.pformat() and node.asdom().toxml() to generate a printable representation of the document structure.
  • Set the configuration variable :confval:`keep_warnings` to True so warnings will be displayed in the generated output.
  • Set the configuration variable :confval:`nitpicky` to True so that Sphinx will complain about references without a known target.
  • Set the debugging options in the Docutils configuration file.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.