diff options
| -rw-r--r-- | CONTRIBUTING.rst | 17 | ||||
| -rw-r--r-- | doc/changes.rst | 5 | ||||
| -rw-r--r-- | doc/internals/contributing.rst | 314 |
3 files changed, 165 insertions, 171 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..73ea1e52e --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,17 @@ +====================== +Contributing to Sphinx +====================== + +Interested in contributing to Sphinx? Hurrah! We welcome all forms of +contribution, including code patches, documentation improvements and bug +reports/feature requests. + +Our contributing guide can be found online at: + +https://www.sphinx-doc.org/en/master/internals/contributing/ + +You can also browse it from this repository from +``doc/internals/contributing/`` + +Sphinx uses GitHub to host source code, track patches and bugs, and more. +Please make an effort to provide as much possible when filing bugs. diff --git a/doc/changes.rst b/doc/changes.rst index ab9795572..b4872784a 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -4,7 +4,8 @@ .. _changes: -Changes in Sphinx -***************** +========= +Changelog +========= .. include:: ../CHANGES diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst index 86513d41f..0e464478a 100644 --- a/doc/internals/contributing.rst +++ b/doc/internals/contributing.rst @@ -1,22 +1,16 @@ -.. highlight:: console - -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. - -.. contents:: - :local: +====================== +Contributing to Sphinx +====================== -The Sphinx source code is managed using Git and is hosted on GitHub. +There are many ways you can contribute to Sphinx, be it filing bug reports or +feature requests, writing new documentation or submitting patches for new or +fixed behavior. This guide serves to illustrate how you can get started with +this. - git clone git://github.com/sphinx-doc/sphinx +Getting help +------------ -.. rubric:: Community +The Sphinx community maintains a number of mailing lists and IRC channels. sphinx-users <sphinx-users@googlegroups.com> Mailing list for user support. @@ -48,35 +42,25 @@ and post that instead. .. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com -Contributing to Sphinx ----------------------- - -The recommended way for new contributors to submit code to Sphinx is to fork -the repository on GitHub 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. - -#. Check for open issues or open a fresh issue to start a discussion around a - feature idea or a bug. -#. If you feel uncomfortable or uncertain about an issue or your changes, feel - free to email the *sphinx-dev* mailing list. -#. Fork `the repository`_ on GitHub to start making your changes to the - ``master`` branch for next MAJOR version, or ``A.x`` branch for next - MINOR version (see :doc:`/internals/release-process`). -#. Write a test which shows that the bug was fixed or that the feature works - as expected. -#. Send a pull request and bug the maintainer until it gets merged and - published. Make sure to add yourself to AUTHORS_ and the change to - CHANGES_. - -.. _`the repository`: https://github.com/sphinx-doc/sphinx -.. _AUTHORS: https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS -.. _CHANGES: https://github.com/sphinx-doc/sphinx/blob/master/CHANGES - - -Getting Started +Writing code +------------ + +The Sphinx source code is managed using Git and is hosted on `GitHub`__. The +recommended way for new contributors to submit code to Sphinx is to fork this +repository and submit a pull request after committing changes to their fork. +The pull request will then need to be approved by one of the core developers +before it is merged into the main repository. + +.. __: https://github.com/sphinx-doc/sphinx + +Getting started ~~~~~~~~~~~~~~~ +Before starting on a patch, we recommend checking for open issues or open a +fresh issue to start a discussion around a feature idea or a bug. If you feel +uncomfortable or uncertain about an issue or your changes, feel free to email +the *sphinx-dev* mailing list. + These are the basic steps needed to start developing on Sphinx. #. Create an account on GitHub. @@ -103,98 +87,40 @@ These are the basic steps needed to start developing on Sphinx. next MAJOR release, use the ``master`` branch. For urgent release, a new PATCH branch must be branched from the newest - release tag (see :doc:`/internals/release-process` for detail). + release tag (see :doc:`release-process` for detail). #. Setup a virtual environment. This is not necessary for unit testing, thanks to ``tox``, but it is necessary if you wish to run ``sphinx-build`` locally or run unit tests - without the help of ``tox``. :: + without the help of ``tox``:: virtualenv ~/.venv . ~/.venv/bin/activate pip install -e . -#. Create a new working branch. Choose any name you like. :: +#. Create a new working branch. Choose any name you like. :: git checkout -b feature-xyz #. Hack, hack, hack. - For tips on working with the code, see the `Coding Guide`_. - -#. Test, test, test. - - Testing is best done through ``tox``, which provides a number of targets and - allows testing against multiple different Python environments: - - * To list all possible targets:: - - tox -av - - * To run unit tests for a specific Python version, such as 3.6:: - - tox -e py36 - - * To run unit tests for a specific Python version and turn on deprecation - warnings on so they're shown in the test output:: - - PYTHONWARNINGS=all tox -e py36 - - * To run code style and type checks:: - - tox -e mypy - tox -e flake8 - - * Arguments to ``pytest`` can be passed via ``tox``, e.g. in order to run a - particular test:: - - tox -e py36 tests/test_module.py::test_new_feature - - * To build the documentation:: - - tox -e docs + Write your code along with tests that shows that the bug was fixed or that + the feature works as expected. - * To build the documentation in multiple formats:: - - tox -e docs -- -b html,latexpdf - - * To run JavaScript tests with `Karma <https://karma-runner.github.io>`_, - execute the following commands (requires `Node.js <https://nodejs.org>`_):: - - npm install - npm run test - - You can also test by installing dependencies in your local environment. :: - - pip install .[test] - - New unit tests should be included in the ``tests`` directory where - necessary: - - * For bug fixes, first add a test that fails without your changes and passes - after they are applied. - - * Tests that need a ``sphinx-build`` run should be integrated in one of the - existing test modules if possible. New tests that to ``@with_app`` and - then ``build_all`` for a few assertions are not good since *the test suite - should not take more than a minute to run*. - -#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not - trivial (small doc updates, typo fixes). Then commit:: +#. Add a bullet point to :file:`CHANGES` if the fix or feature is not trivial + (small doc updates, typo fixes), then commit:: git commit -m '#42: Add useful new feature that does this.' GitHub recognizes certain phrases that can be used to automatically - update the issue tracker. - - For example:: + update the issue tracker. For example:: git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' would close issue #42. -#. Push changes in the branch to your forked repository on GitHub. :: +#. Push changes in the branch to your forked repository on GitHub:: git push origin feature-xyz @@ -203,17 +129,10 @@ These are the basic steps needed to start developing on Sphinx. #. Wait for a core developer to review your changes. - -Translations +Coding style ~~~~~~~~~~~~ -The Sphinx core messages and documentations are translated on `Transifex -<https://www.transifex.com/>`_. Please join `Sphinx project on Transifex -<https://www.transifex.com/sphinx-doc/>`_ and translate them. - - -Coding Guide ------------- +Please follow these guidelines when writing code for Sphinx: * Try to use the same code style as used in the rest of the project. See the `Pocoo Styleguide`__ for more information. @@ -232,76 +151,100 @@ Coding Guide * Add appropriate unit tests. +Style and type checks can be run using ``tox``:: -Debugging Tips -~~~~~~~~~~~~~~ + tox -e mypy + tox -e flake8 -* 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. +Unit tests +~~~~~~~~~~ -* Use the :option:`sphinx-build -P` option to run ``pdb`` on exceptions. +Sphinx is tested using `pytest`__ for Python code and `Karma`__ for JavaScript. -* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable - representation of the document structure. +.. __: https://docs.pytest.org/en/latest/ +.. __: https://karma-runner.github.io -* Set the configuration variable :confval:`keep_warnings` to ``True`` so - warnings will be displayed in the generated output. +To run Python unit tests, we recommend using ``tox``, which provides a number +of targets and allows testing against multiple different Python environments: -* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx - will complain about references without a known target. +* To list all possible targets:: -* Set the debugging options in the `Docutils configuration file - <http://docutils.sourceforge.net/docs/user/config.html>`_. + tox -av -* JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) - are generated by this - `modified snowballcode generator <https://github.com/shibukawa/snowball>`_. - Generated `JSX <https://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:: +* To run unit tests for a specific Python version, such as Python 3.6:: - npm install - node_modules/.bin/grunt build # -> dest/*.global.js + tox -e py36 +* To run unit tests for a specific Python version and turn on deprecation + warnings on so they're shown in the test output:: -Unit Testing ------------- + PYTHONWARNINGS=all tox -e py36 -Sphinx has been tested with pytest runner. Sphinx developers write unit tests -using pytest notation. Utility functions and pytest fixtures for testing are -provided in ``sphinx.testing``. If you are a developer of Sphinx extensions, -you can write unit tests with using pytest. At this time, ``sphinx.testing`` -will help your test implementation. +* Arguments to ``pytest`` can be passed via ``tox``, e.g. in order to run a + particular test:: -How to use pytest fixtures that are provided by ``sphinx.testing``? -You can require ``'sphinx.testing.fixtures'`` in your test modules or -``conftest.py`` files like this:: + tox -e py36 tests/test_module.py::test_new_feature - pytest_plugins = 'sphinx.testing.fixtures' +You can also test by installing dependencies in your local environment:: -If you want to know more detailed usage, please refer to ``tests/conftest.py`` -and other ``test_*.py`` files under ``tests`` directory. + pip install .[test] -.. note:: +To run JavaScript tests, use ``npm``:: - Prior to Sphinx - 1.5.2, Sphinx was running the test with nose. + npm install + npm run test -.. versionadded:: 1.6 - ``sphinx.testing`` as a experimental. +New unit tests should be included in the ``tests`` directory where +necessary: + +* For bug fixes, first add a test that fails without your changes and passes + after they are applied. + +* Tests that need a ``sphinx-build`` run should be integrated in one of the + existing test modules if possible. New tests that to ``@with_app`` and + then ``build_all`` for a few assertions are not good since *the test suite + should not take more than a minute to run*. .. versionadded:: 1.8 + Sphinx also runs JavaScript tests. +.. versionadded:: 1.6 + + ``sphinx.testing`` is added as a experimental. -Release procedures ------------------- +.. versionchanged:: 1.5.2 -The release procedures are listed on ``utils/release-checklist``. + Sphinx was switched from nose to pytest. +.. todo:: The below belongs in the developer guide -Locale Updates -~~~~~~~~~~~~~~ +Utility functions and pytest fixtures for testing are provided in +``sphinx.testing``. If you are a developer of Sphinx extensions, you can write +unit tests with using pytest. At this time, ``sphinx.testing`` will help your +test implementation. + +How to use pytest fixtures that are provided by ``sphinx.testing``? You can +require ``'sphinx.testing.fixtures'`` in your test modules or ``conftest.py`` +files like this:: + + pytest_plugins = 'sphinx.testing.fixtures' + +If you want to know more detailed usage, please refer to ``tests/conftest.py`` +and other ``test_*.py`` files under ``tests`` directory. + + +Writing documentation +--------------------- + +.. todo:: Add a more extensive documentation contribution guide. + +You can build documentation using ``tox``:: + + tox -e docs + +Translations +~~~~~~~~~~~~ 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 @@ -325,9 +268,42 @@ identifier and put ``sphinx.po`` in there. Don't forget to update the possible values for :confval:`language` in ``doc/usage/configuration.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. +<https://www.transifex.com/sphinx-doc/>`_. There ``tx`` client tool, which is +provided by the ``transifex_client`` Python package, 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 + :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 + <https://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:: + + npm install + node_modules/.bin/grunt build # -> dest/*.global.js |