+Sphinx Developer's Guide
+ 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
+ hg clone https://bitbucket.org/birkenfeld/sphinx
+ Mailing list for user support.
+ 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 <http://dev.pocoo.org/irclogs/>`_.
+.. _`BitBucket`: http://bitbucket.org
+.. _`Mercurial`: http://mercurial.selenic.com/
+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
+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
+.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues
+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
+ <https://bitbucket.org/birkenfeld/sphinx>`_) using the BitBucket interface.
+#. Clone the forked repository to your machine. ::
+ hg clone https://bitbucket.org/USERNAME/sphinx-fork
+#. Checkout the appropriate branch.
+ For changes that should be included in the next minor release (namely bug
+ fixes), use the ``stable`` branch. ::
+ For new features or other substantial changes that should wait until the
+ next major release, use the ``default`` branch.
+#. Setup your Python environment. ::
+ . ~/sphinxenv/bin/activate
+ For tips on working with the code, see the `Coding Guide`_.
+ Build the documentation and check the output for different builders::
+ make clean html text man info latexpdf
+ Run the unit tests under different Python environments using
+ 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.'
+ __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code
+#. 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
+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 :file:`CHANGES` entry.
+* Using Mercurial named branches other than ``default`` and ``stable`` is not
+* Try to use the same code style as used in the rest of the project. See the
+ `Pocoo Styleguide`__ for more information.
+ __ http://flask.pocoo.org/docs/styleguide/
+* 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
+* When adding a new configuration variable, be sure to document it and update
+* Use the included :program:`utils/check_sources.py` script to check for
+ common formatting issues (trailing whitespace, lengthy lines, etc).
+* Add appropriate unit tests.
+* 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