mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
258 lines
8.7 KiB
ReStructuredText
258 lines
8.7 KiB
ReStructuredText
Sphinx Developer's Guide
|
|
========================
|
|
|
|
.. 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 <sphinx-users@googlegroups.com>
|
|
Mailing list for user support.
|
|
|
|
sphinx-dev <sphinx-dev@googlegroups.com>
|
|
Mailing list for development related discussions.
|
|
|
|
#sphinx-doc on irc.freenode.net
|
|
IRC channel for development questions and user support.
|
|
|
|
.. _`BitBucket`: https://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
|
|
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`: https://bitbucket.org/birkenfeld/sphinx/issues
|
|
|
|
|
|
Contributing to 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.
|
|
|
|
|
|
Getting Started
|
|
~~~~~~~~~~~~~~~
|
|
|
|
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
|
|
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.
|
|
|
|
#. Optional: setup a virtual 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. Possible steps:
|
|
|
|
* Run the unit tests::
|
|
|
|
pip install nose mock
|
|
make test
|
|
|
|
* Build the documentation and check the output for different builders::
|
|
|
|
cd doc
|
|
make clean html 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.
|
|
|
|
#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not trivial
|
|
(small doc updates, typo fixes). Then commit::
|
|
|
|
hg commit -m '#42: 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/Resolve+issues+automatically+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.
|
|
|
|
|
|
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 :file:`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 <http://babel.edgewall.org>`_ 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 :confval:`language` in ``doc/config.rst``.
|
|
|
|
The Sphinx core messages can also be translated on `Transifex
|
|
<https://www.transifex.com/>`_. 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.
|
|
|
|
|
|
Coding Guide
|
|
------------
|
|
|
|
* 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` if it's important enough.
|
|
|
|
* Use the included :program:`utils/check_sources.py` script to check for
|
|
common formatting issues (trailing whitespace, lengthy lines, etc).
|
|
|
|
* Add appropriate unit tests.
|
|
|
|
|
|
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
|
|
<http://docutils.sourceforge.net/docs/user/config.html>`_.
|
|
|
|
* JavaScript stemming algorithms in `sphinx/search/*.py` (except `en.py`) are
|
|
generated by this
|
|
`modified snowballcode generator <https://github.com/shibukawa/snowball>`_.
|
|
Generated `JSX <http://jsx.github.io/>`_ files are
|
|
in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_.
|
|
You can get the resulting JavaScript files using the following command:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ npm install
|
|
$ node_modules/.bin/grunt build # -> dest/*.global.js
|