Getting Started

These are the basic steps needed to start developing on Sphinx.

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 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 repository on BitBucket.

   hg push

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

11. Wait for a core developer to review your changes.

Core Developers

The core developers of Sphinx have write access to the main repository. They can commit changes, accept/reject pull requests, and manage items on the issue tracker.

You do not need to be a core developer or have write access to be involved in the development of Sphinx. You can submit patches or create pull requests from forked repositories and have a core developer add the changes for you.

The following are some general guidelines for core developers:

• Questionable or extensive changes should be submitted as a pull request instead of being committed directly to the main repository. The pull request should be reviewed by another core developer before it is merged.
• Trivial changes can be committed directly but be sure to keep the repository in a good working state and that all tests pass before pushing your changes.
• When committing code written by someone else, please attribute the original author in the commit message and any relevant CHANGES entry.
• Using Mercurial named branches other than default and stable is not encouraged.

Locale updates

The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext .po files translated from the master template sphinx/locale/sphinx.pot.

Sphinx uses Babel to extract messages and maintain the catalog files. It is integrated in setup.py:

• Use python setup.py extract_messages to update the .pot template.
• Use python setup.py update_catalog to update all existing language catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in the template file.
• Use python setup.py compile_catalog to compile the .po files to binary .mo files and .js files.

When an updated .po file is submitted, run compile_catalog to commit both the source and the compiled catalogs.

When a new locale is submitted, add a new directory with the ISO 639-1 language identifier and put sphinx.po in there. Don’t forget to update the possible values for language in doc/config.rst.

The Sphinx core messages can also be translated on Transifex. There exists a client tool named tx in the Python package “transifex_client”, which can be used to pull translations in .po format from Transifex. To do this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is an existing language identifier. It is good practice to run python setup.py update_catalog afterwards to make sure the .po file has the canonical Babel formatting.

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 sphinx-build -E option.
• Use the 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 keep_warnings to True so warnings will be displayed in the generated output.
• Set the configuration variable nitpicky to True so that Sphinx will complain about references without a known target.
• Set the debugging options in the Docutils configuration file.