IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: Rework contributing document, re-add CONTRIBUTING

Browse Source 
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 2020-05-30 15:08:50 +01:00
parent d3021f644f
commit 6b480c97b2
3 changed files with 164 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
CONTRIBUTING.rst Normal file
View 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.

5
doc/changes.rst
View File

@ -4,7 +4,8 @@
.. _changes: .. _changes:
Changes in Sphinx =========
***************** Changelog
=========
.. include:: ../CHANGES .. include:: ../CHANGES

308
doc/internals/contributing.rst
View File

@ -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 The Sphinx community maintains a number of mailing lists and IRC channels.
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
sphinx-users <sphinx-users@googlegroups.com> sphinx-users <sphinx-users@googlegroups.com>
Mailing list for user support. Mailing list for user support.
@ -48,35 +42,25 @@ and post that instead.
.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com .. _`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 Sphinx source code is managed using Git and is hosted on `GitHub`__. The
the repository on GitHub and then submit a pull request after recommended way for new contributors to submit code to Sphinx is to fork this
committing the changes. The pull request will then need to be approved by one repository and submit a pull request after committing changes to their fork.
of the core developers before it is merged into the main repository. 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 .. __: https://github.com/sphinx-doc/sphinx
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 Getting started
.. _AUTHORS: https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS
.. _CHANGES: https://github.com/sphinx-doc/sphinx/blob/master/CHANGES
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. These are the basic steps needed to start developing on Sphinx.
#. Create an account on GitHub. #. 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. next MAJOR release, use the ``master`` branch.
For urgent release, a new PATCH branch must be branched from the newest 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. #. Setup a virtual environment.
This is not necessary for unit testing, thanks to ``tox``, but it is 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 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 virtualenv ~/.venv
. ~/.venv/bin/activate . ~/.venv/bin/activate
@ -121,80 +105,22 @@ These are the basic steps needed to start developing on Sphinx.
#. Hack, hack, hack. #. 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. #. Add a bullet point to :file:`CHANGES` if the fix or feature is not trivial
(small doc updates, typo fixes), then commit::
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::
git commit -m '#42: Add useful new feature that does this.' git commit -m '#42: Add useful new feature that does this.'
GitHub recognizes certain phrases that can be used to automatically GitHub recognizes certain phrases that can be used to automatically
update the issue tracker. update the issue tracker. For example::
For example::
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
would close issue #42. 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 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. #. Wait for a core developer to review your changes.
Coding style
Translations
~~~~~~~~~~~~ ~~~~~~~~~~~~
The Sphinx core messages and documentations are translated on `Transifex Please follow these guidelines when writing code for Sphinx:
<https://www.transifex.com/>`_. Please join `Sphinx project on Transifex
<https://www.transifex.com/sphinx-doc/>`_ and translate them.
Coding Guide
------------
* Try to use the same code style as used in the rest of the project. See the * Try to use the same code style as used in the rest of the project. See the
`Pocoo Styleguide`__ for more information. `Pocoo Styleguide`__ for more information.
@ -232,76 +151,100 @@ Coding Guide
* Add appropriate unit tests. * 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 Unit tests
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. Sphinx is tested using `pytest`__ for Python code and `Karma`__ for JavaScript.
* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable .. __: https://docs.pytest.org/en/latest/
representation of the document structure. .. __: https://karma-runner.github.io
* Set the configuration variable :confval:`keep_warnings` to ``True`` so To run Python unit tests, we recommend using ``tox``, which provides a number
warnings will be displayed in the generated output. of targets and allows testing against multiple different Python environments:
* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx * To list all possible targets::
will complain about references without a known target.
* Set the debugging options in the `Docutils configuration file tox -av
<http://docutils.sourceforge.net/docs/user/config.html>`_.
* JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) * To run unit tests for a specific Python version, such as Python 3.6::
are generated by this
`modified snowballcode generator <https://github.com/shibukawa/snowball>`_. tox -e py36
Generated `JSX <https://jsx.github.io/>`_ files are
in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_. * To run unit tests for a specific Python version and turn on deprecation
You can get the resulting JavaScript files using the following command:: 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 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 * Tests that need a ``sphinx-build`` run should be integrated in one of the
using pytest notation. Utility functions and pytest fixtures for testing are existing test modules if possible. New tests that to ``@with_app`` and
provided in ``sphinx.testing``. If you are a developer of Sphinx extensions, then ``build_all`` for a few assertions are not good since *the test suite
you can write unit tests with using pytest. At this time, ``sphinx.testing`` should not take more than a minute to run*.
will help your test implementation.
How to use pytest fixtures that are provided by ``sphinx.testing``? .. versionadded:: 1.8
You can require ``'sphinx.testing.fixtures'`` in your test modules or
``conftest.py`` files like this:: 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' pytest_plugins = 'sphinx.testing.fixtures'
If you want to know more detailed usage, please refer to ``tests/conftest.py`` If you want to know more detailed usage, please refer to ``tests/conftest.py``
and other ``test_*.py`` files under ``tests`` directory. 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 .. todo:: Add a more extensive documentation contribution guide.
``sphinx.testing`` as a experimental.
.. versionadded:: 1.8 You can build documentation using ``tox``::
Sphinx also runs JavaScript tests.
tox -e docs
Release procedures Translations
------------------ ~~~~~~~~~~~~
The release procedures are listed on ``utils/release-checklist``.
Locale Updates
~~~~~~~~~~~~~~
The parts of messages in Sphinx that go into builds are translated into several 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 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``. values for :confval:`language` in ``doc/usage/configuration.rst``.
The Sphinx core messages can also be translated on `Transifex The Sphinx core messages can also be translated on `Transifex
<https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the <https://www.transifex.com/sphinx-doc/>`_. There ``tx`` client tool, which is
Python package "transifex_client", which can be used to pull translations in provided by the ``transifex_client`` Python package, can be used to pull
``.po`` format from Transifex. To do this, go to ``sphinx/locale`` and then run translations in ``.po`` format from Transifex. To do this, go to
``tx pull -f -l LANG`` where LANG is an existing language identifier. It is ``sphinx/locale`` and then run ``tx pull -f -l LANG`` where ``LANG`` is an
good practice to run ``python setup.py update_catalog`` afterwards to make sure existing language identifier. It is good practice to run ``python setup.py
the ``.po`` file has the canonical Babel formatting. 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