mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
docs: Rework contributing document, re-add CONTRIBUTING
Reorder this to flow a little better and re-add the CONTRIBUTING document, which now simply points to the main documentation. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
parent
d3021f644f
commit
6b480c97b2
17
CONTRIBUTING.rst
Normal file
17
CONTRIBUTING.rst
Normal file
@ -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.
|
||||
@ -4,7 +4,8 @@
|
||||
|
||||
.. _changes:
|
||||
|
||||
Changes in Sphinx
|
||||
*****************
|
||||
=========
|
||||
Changelog
|
||||
=========
|
||||
|
||||
.. include:: ../CHANGES
|
||||
|
||||
@ -1,22 +1,16 @@
|
||||
.. highlight:: console
|
||||
======================
|
||||
Contributing to Sphinx
|
||||
======================
|
||||
|
||||
Sphinx Developer's Guide
|
||||
========================
|
||||
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.
|
||||
|
||||
.. topic:: Abstract
|
||||
Getting help
|
||||
------------
|
||||
|
||||
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:
|
||||
|
||||
The Sphinx source code is managed using Git and is hosted on GitHub.
|
||||
|
||||
git clone git://github.com/sphinx-doc/sphinx
|
||||
|
||||
.. 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
|
||||
----------------------
|
||||
Writing code
|
||||
------------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
#. 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_.
|
||||
.. __: https://github.com/sphinx-doc/sphinx
|
||||
|
||||
.. _`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
|
||||
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,13 +87,13 @@ 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
|
||||
@ -121,80 +105,22 @@ These are the basic steps needed to start developing on Sphinx.
|
||||
|
||||
#. Hack, hack, hack.
|
||||
|
||||
For tips on working with the code, see the `Coding Guide`_.
|
||||
Write your code along with tests that shows that the bug was fixed or that
|
||||
the feature works as expected.
|
||||
|
||||
#. 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
|
||||
|
||||
* 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::
|
||||
|
||||
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
|
||||
|
||||
* 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
|
||||
|
||||
You can also test by installing dependencies in your local environment::
|
||||
|
||||
pip install .[test]
|
||||
|
||||
To run JavaScript tests, use ``npm``::
|
||||
|
||||
npm install
|
||||
node_modules/.bin/grunt build # -> dest/*.global.js
|
||||
npm run test
|
||||
|
||||
New unit tests should be included in the ``tests`` directory where
|
||||
necessary:
|
||||
|
||||
Unit Testing
|
||||
------------
|
||||
* For bug fixes, first add a test that fails without your changes and passes
|
||||
after they are applied.
|
||||
|
||||
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.
|
||||
* 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*.
|
||||
|
||||
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::
|
||||
.. versionadded:: 1.8
|
||||
|
||||
Sphinx also runs JavaScript tests.
|
||||
|
||||
.. versionadded:: 1.6
|
||||
|
||||
``sphinx.testing`` is added as a experimental.
|
||||
|
||||
.. versionchanged:: 1.5.2
|
||||
|
||||
Sphinx was switched from nose to pytest.
|
||||
|
||||
.. todo:: The below belongs in the developer guide
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
Prior to Sphinx - 1.5.2, Sphinx was running the test with nose.
|
||||
Writing documentation
|
||||
---------------------
|
||||
|
||||
.. versionadded:: 1.6
|
||||
``sphinx.testing`` as a experimental.
|
||||
.. todo:: Add a more extensive documentation contribution guide.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
Sphinx also runs JavaScript tests.
|
||||
You can build documentation using ``tox``::
|
||||
|
||||
tox -e docs
|
||||
|
||||
Release procedures
|
||||
------------------
|
||||
|
||||
The release procedures are listed on ``utils/release-checklist``.
|
||||
|
||||
|
||||
Locale Updates
|
||||
~~~~~~~~~~~~~~
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user