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.
IRC channel for development questions and user support.
This channel is shared with other Pocoo projects. Archived logs are available here.
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.
The recommended way for new contributors to submit code to Sphinx is to fork the Mercurial repository on BitBucket and then submit a pull request after committing the changes. The pull request will then need to be approved by one of the core developers before it is merged into the main repository.
These are the basic steps needed to start developing on Sphinx.
Create an account on BitBucket.
Fork the main Sphinx repository (birkenfeld/sphinx) using the BitBucket interface.
Clone the forked repository to your machine.
hg clone https://bitbucket.org/USERNAME/sphinx-fork cd sphinx-fork
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.
Setup your Python environment.
virtualenv ~/sphinxenv . ~/sphinxenv/bin/activate pip install -e .
Hack, hack, hack.
For tips on working with the code, see the Coding Guide.
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.
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.
hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
would close issue #42.
Push changes to your forked repository on BitBucket.
Submit a pull request from your repository to birkenfeld/sphinx using the BitBucket interface.
Wait for a core developer to review your changes.
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: