6 files changed, 550 insertions, 0 deletions
diff --git a/doc/internals/authors.rst b/doc/internals/authors.rst
new file mode 100644
index 0000000..929acc9
--- /dev/null
+++ b/doc/internals/authors.rst
@@ -0,0 +1,9 @@
+:tocdepth: 2
+
+.. _authors:
+
+==============
+Sphinx authors
+==============
+
+.. include:: ../../AUTHORS
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..d633f9c
--- /dev/null
+++ b/doc/internals/contributing.rst
@@ -0,0 +1,337 @@
+======================
+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 using ``tox``::
+
+    tox -e mypy
+    tox -e flake8
+
+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.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
+    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 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.
+
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We use `the tox tool <https://tox.wiki/en/latest/>`__ to quickly build the
+documentation. Tox is kind-of like a Makefile, but includes the ability to
+intsall an isolated environment used to run each task.
+
+To build the documentation with ``tox``, run the following command::
+
+    tox -e docs
+
+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::
+
+    tox -e docs-live
+
+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/*.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
diff --git a/doc/internals/index.rst b/doc/internals/index.rst
new file mode 100644
index 0000000..c52f32a
--- /dev/null
+++ b/doc/internals/index.rst
@@ -0,0 +1,16 @@
+====================
+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
+   authors
diff --git a/doc/internals/organization.rst b/doc/internals/organization.rst
new file mode 100644
index 0000000..4fc1598
--- /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..a23ace0
--- /dev/null
+++ b/doc/internals/release-process.rst
@@ -0,0 +1,127 @@
+========================
+Sphinx's release process
+========================
+
+Branch Model
+------------
+
+Sphinx project uses following branches for developing that conforms to Semantic
+Versioning 2.0.0 (refs: https://semver.org/ ).
+
+``master``
+    Development for MAJOR version.
+    All changes including incompatible behaviors and public API updates are
+    allowed.
+
+``A.x`` (ex. ``2.x``)
+    Where ``A.x`` is the ``MAJOR.MINOR`` release.  Used to maintain current
+    MINOR release. All changes are allowed if the change preserves
+    backwards-compatibility of API and features.
+
+    Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
+    new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
+    deleted and replaced by an equivalent tag.
+
+``A.B.x`` (ex. ``2.4.x``)
+    Where ``A.B.x`` is the ``MAJOR.MINOR.PATCH`` release.  Only
+    backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
+    version is used for urgent bug fix.
+
+    ``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
+    release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
+    release is needed. When new PATCH version is released, the branch will be
+    deleted and replaced by an equivalent tag (ex. v2.3.1).
+
+
+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
+-----------------------------
+
+The minimum Python version Sphinx supports is the default Python version
+installed in the oldest `Long Term Support version of
+Ubuntu <https://ubuntu.com/about/release-cycle>`_ that has standard support.
+For example, as of July 2021, Ubuntu 16.04 has just entered extended
+security maintenance (therefore, it doesn't count as standard support) and
+the oldest LTS release to consider is Ubuntu 18.04 LTS, supported until
+April 2023 and shipping Python 3.6.
+
+This is a summary table with the current policy:
+
+========== ========= ======
+Date       Ubuntu    Python
+========== ========= ======
+April 2021 18.04 LTS 3.6+
+---------- --------- ------
+April 2023 20.04 LTS 3.8+
+========== ========= ======
+
+Release procedures
+------------------
+
+The release procedures are listed in ``utils/release-checklist``.