开发手册 ======== .. topic:: 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 .. rubric:: Community sphinx-users Mailing list for user support. sphinx-dev 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 `_. .. _`BitBucket`: http://bitbucket.org .. _`Mercurial`: http://mercurial.selenic.com/ Bug报告和功能反馈 ----------------- 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. .. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues 贡献给Sphinx ---------------------- 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 :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. #. 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. __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code #. Push changes to your forked repository on BitBucket. :: hg push #. 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: * 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 encouraged. 编码指南 ------------ * 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 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). * 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 `_.