diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/internals/code-of-conduct.rst | 5 | ||||
| -rw-r--r-- | doc/internals/contributing.rst | 332 | ||||
| -rw-r--r-- | doc/internals/index.rst | 15 | ||||
| -rw-r--r-- | doc/internals/organization.rst | 56 | ||||
| -rw-r--r-- | doc/internals/release-process.rst | 125 |
5 files changed, 533 insertions, 0 deletions
diff --git a/doc/internals/code-of-conduct.rst b/doc/internals/code-of-conduct.rst new file mode 100644 index 0000000..8e31ef0 --- /dev/null +++ b/doc/internals/code-of-conduct.rst @@ -0,0 +1,5 @@ +:tocdepth: 2 + +.. _code_of_conduct: + +.. include:: ../../CODE_OF_CONDUCT diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst new file mode 100644 index 0000000..195f6a5 --- /dev/null +++ b/doc/internals/contributing.rst @@ -0,0 +1,332 @@ +====================== +Contributing to Sphinx +====================== + +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. + +Get help +-------- + +The Sphinx community maintains a number of mailing lists and IRC channels. + +Stack Overflow with tag `python-sphinx`_ + Questions and answers about use and development. + +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.libera.chat + IRC channel for development questions and user support. + +.. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx + +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 GitHub 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 unhandled +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://github.com/sphinx-doc/sphinx/issues +.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com + + +Contribute 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 + +.. _contribute-get-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. + +#. Fork the main Sphinx repository (`sphinx-doc/sphinx + <https://github.com/sphinx-doc/sphinx>`_) using the GitHub interface. + +#. Clone the forked repository to your machine. :: + + git clone https://github.com/USERNAME/sphinx + cd sphinx + +#. Checkout the appropriate branch. + + Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ). + + For changes that preserves backwards-compatibility of API and features, + they should be included in the next MINOR release, use the ``A.x`` branch. + :: + + git checkout A.x + + For incompatible or other substantial changes that should wait until the + next MAJOR release, use the ``master`` branch. + + For urgent release, a new PATCH branch must be branched from the newest + 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``:: + + virtualenv ~/.venv + . ~/.venv/bin/activate + pip install -e . + +#. Create a new working branch. Choose any name you like. :: + + git checkout -b feature-xyz + +#. Hack, hack, hack. + + Write your code along with tests that shows that the bug was fixed or that + the feature works as expected. + +#. 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:: + + 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:: + + git push origin feature-xyz + +#. Submit a pull request from your branch to the respective branch (``master`` + or ``A.x``). + +#. Wait for a core developer to review your changes. + +Coding style +~~~~~~~~~~~~ + +Please follow these guidelines when writing code for Sphinx: + +* Try to use the same code style as used in the rest of the project. + +* 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/cmd/quickstart.py` if it's important enough. + +* Add appropriate unit tests. + +Style and type checks can be run as follows:: + + ruff . + mypy sphinx/ + +Unit tests +~~~~~~~~~~ + +Sphinx is tested using `pytest`__ for Python code and `Karma`__ for JavaScript. + +.. __: https://docs.pytest.org/en/latest/ +.. __: https://karma-runner.github.io + +To run Python unit tests, we recommend using ``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 Python 3.10:: + + tox -e py310 + +* To run unit tests for a specific Python version and turn on deprecation + warnings so they're shown in the test output:: + + PYTHONWARNINGS=error tox -e py310 + +* Arguments to ``pytest`` can be passed via ``tox``, e.g., in order to run a + particular test:: + + tox -e py310 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 run 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*. + +.. 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 by 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 the ``tests`` directory. + + +Contribute documentation +------------------------ + +Contributing to documentation involves modifying the source files found in the +``doc/`` folder. To get started, you should first follow :ref:`contribute-get-started`, +and then take the steps below to work with the documentation. + +The following sections describe how to get started with contributing +documentation, as well as key aspects of a few different tools that we use. + +.. todo:: Add a more extensive documentation contribution guide. + +Build the documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +To build the documentation, run the following command:: + + sphinx-build -M html ./doc ./build/sphinx -W --keep-going + +This will parse the Sphinx documentation's source files and generate HTML for +you to preview in ``build/sphinx/html``. + +You can also build a **live version of the documentation** that you can preview +in the browser. It will detect changes and reload the page any time you make +edits. To do so, run the following command:: + + sphinx-autobuild ./doc ./build/sphinx/ + +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 +master template :file:`sphinx/locale/sphinx.pot`. + +Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages +and maintain the catalog files. The ``utils`` directory contains a helper +script, ``babel_runner.py``. + +* Use ``python babel_runner.py extract`` to update the ``.pot`` template. +* Use ``python babel_runner.py update`` to update all existing language + catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the + template file. +* Use ``python babel_runner.py compile`` to compile the ``.po`` files to binary + ``.mo`` files and ``.js`` files. + +When an updated ``.po`` file is submitted, run +``python babel_runner.py compile`` 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/usage/configuration.rst``. + +The Sphinx core messages can also be translated on `Transifex +<https://www.transifex.com/sphinx-doc/sphinx-1/>`_. 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 babel_runner.py update`` 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 + <https://docutils.sourceforge.io/docs/user/config.html>`_. + +* JavaScript stemming algorithms in ``sphinx/search/non-minified-js/*.js`` + are generated using `snowball <https://github.com/snowballstem/snowball>`_ + by cloning the repository, executing ``make dist_libstemmer_js`` and then + unpacking the tarball which is generated in ``dist`` directory. + + Minified files in ``sphinx/search/minified-js/*.js`` are generated from + non-minified ones using ``uglifyjs`` (installed via npm), with ``-m`` + option to enable mangling. diff --git a/doc/internals/index.rst b/doc/internals/index.rst new file mode 100644 index 0000000..187082e --- /dev/null +++ b/doc/internals/index.rst @@ -0,0 +1,15 @@ +==================== +Contribute to Sphinx +==================== + +This guide contains information about the Sphinx open source project itself. +This is where you can find information about how Sphinx is managed and learn +how to contribute to the project. + +.. toctree:: + :maxdepth: 2 + + contributing + release-process + organization + code-of-conduct diff --git a/doc/internals/organization.rst b/doc/internals/organization.rst new file mode 100644 index 0000000..9dec923 --- /dev/null +++ b/doc/internals/organization.rst @@ -0,0 +1,56 @@ +================================== +Organization of the Sphinx project +================================== + +The guide explains how the Sphinx project is organized. + +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. + +Guidelines +~~~~~~~~~~ + +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. + +Membership +~~~~~~~~~~ + +Core membership is predicated on continued active contribution to the project. +In general, prospective cores should demonstrate: + +- a good understanding of one of more components of Sphinx + +- a history of helpful, constructive contributions + +- a willingness to invest time improving Sphinx + +Refer to :doc:`contributing` for more information on how you can get started. + +Other contributors +------------------ + +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. + +Similarly, contributions are not limited to code patches. We also welcome help +triaging bugs, input on design decisions, reviews of existing patches and +documentation improvements. More information can be found in +:doc:`contributing`. + +A list of people that have contributed to Sphinx can be found in +:doc:`../authors`. diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst new file mode 100644 index 0000000..50648cd --- /dev/null +++ b/doc/internals/release-process.rst @@ -0,0 +1,125 @@ +======================== +Sphinx's release process +======================== + +Versioning +---------- + +Sphinx adheres to :pep:`440` versions, with a ``major.minor.micro`` scheme for +the *release segment* (e.g. 1.2.3). +The major, minor, and micro version parts should be altered as follows: + +* The major version part should be incremented for incompatible behavior change and + public API updates. + +* The minor version part should be incremented for most releases of Sphinx, where + backwards-compatibility of API and features are preserves. + +* The micro version part should only be incremented for urgent bugfix-only releases. + +When the major version part is incremented, the minor and micro version parts +must be set to ``0``. +When the minor version part is incremented, the micro version part must be set +to ``0``. + +New major versions should come with a beta-testing period before the final +release. + + +Deprecating a feature +--------------------- + +There are a couple reasons that code in Sphinx might be deprecated: + +* If a feature has been improved or modified in a backwards-incompatible way, + the old feature or behavior will be deprecated. + +* Sometimes Sphinx will include a backport of a Python library that's not + included in a version of Python that Sphinx currently supports. When Sphinx + no longer needs to support the older version of Python that doesn't include + the library, the library will be deprecated in Sphinx. + +As the :ref:`deprecation-policy` describes, the first release of Sphinx that +deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning`` +(where ``XX`` is the Sphinx version where the feature will be removed) when the +deprecated feature is invoked. Assuming we have good test coverage, these +warnings are converted to errors when running the test suite with warnings +enabled:: + + pytest -Wall + +Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or +silence any warnings generated when running the tests. + + +.. _deprecation-policy: + +Deprecation policy +------------------ + +MAJOR and MINOR releases may deprecate certain features from previous +releases. If a feature is deprecated in a release A.x, it will continue to +work in all A.x.x versions (for all versions of x). It will continue to work +in all B.x.x versions but raise deprecation warnings. Deprecated features +will be removed at the C.0.0. It means the deprecated feature will work during +2 MAJOR releases at least. + +So, for example, if we decided to start the deprecation of a function in +Sphinx 2.x: + +* Sphinx 2.x will contain a backwards-compatible replica of the function + which will raise a ``RemovedInSphinx40Warning``. + This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it + will not get displayed by default. + +* Sphinx 3.x will still contain the backwards-compatible replica, but + ``RemovedInSphinx40Warning`` will be a subclass of + :exc:`python:DeprecationWarning` then, and gets displayed by default. + +* Sphinx 4.0 will remove the feature outright. + +Deprecation warnings +~~~~~~~~~~~~~~~~~~~~ + +Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default, if +:envvar:`python:PYTHONWARNINGS` is not set. Therefore you can disable them +using: + +* ``PYTHONWARNINGS= make html`` (Linux/Mac) +* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) +* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) + +But you can also explicitly enable the pending ones using e.g. +``PYTHONWARNINGS=default`` (see the :ref:`Python docs on configuring warnings +<python:describing-warning-filters>`) for more details. + +Python version support policy +----------------------------- + +Sphinx supports at all minor versions of Python released in the past 42 months +from the anticipated release date with a minimum of 3 minor versions of Python. +This policy is derived from `NEP 29`_, a scientific Python domain standard. + +.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html + +For example, a version of Sphinx released in May 2024 would support Python 3.10, +3.11, and 3.12. + +This is a summary table with the current policy: + +=========== ====== +Date Python +=========== ====== +26 Dec 2021 3.8+ +----------- ------ +14 Apr 2023 3.9+ +----------- ------ +05 Apr 2024 3.10+ +----------- ------ +04 Apr 2025 3.11+ +=========== ====== + +Release procedures +------------------ + +The release procedures are listed in ``utils/release-checklist``. |