Merge branch '3.x'

6 files changed, 58 insertions, 201 deletions

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index 5e588acc4..9e9f7af56 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -33,9 +33,9 @@
     <li>{%trans path=pathto('ext/builtins')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of
       docstrings from Python modules (API docs), and
       <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li>
-    <li>{%trans path=pathto('develop')%}<b>Contributed extensions:</b> more than
-      50 extensions <a href="{{ path }}#extensions">contributed by users</a>
-      in a second repository; most of them installable from PyPI{%endtrans%}</li>
+    <li>{%trans path=pathto("usage/extensions")%}<b>Contributed extensions:</b> dozens of
+      extensions <a href="{{ path }}#third-party-extensions">contributed by users</a>;
+      most of them installable from PyPI{%endtrans%}</li>
   </ul>
   <p>{%trans%}
     Sphinx uses <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html
index e3bb37dce..238fb52b7 100644
--- a/doc/_themes/sphinx13/layout.html
+++ b/doc/_themes/sphinx13/layout.html
@@ -67,7 +67,7 @@
     <li><a href="{{ pathto('index') }}">Home</a></li>
     <li><a href="{{ pathto('usage/installation') }}">Get it</a></li>
     <li><a href="{{ pathto('contents') }}">Docs</a></li>
-    <li><a href="{{ pathto('develop') }}">Extend/Develop</a></li>
+    <li><a href="{{ pathto('development') }}">Extend</a></li>
   </ul>
   <div>
     <a href="{{ pathto('index') }}">
diff --git a/doc/develop.rst b/doc/develop.rst
deleted file mode 100644
index 3bbc220b8..000000000
--- a/doc/develop.rst
+++ /dev/null
@@ -1,153 +0,0 @@
-:orphan:
-
-Sphinx development
-==================
-
-Sphinx is a maintained by a group of volunteers.  We value every contribution!
-
-* The code can be found in a Git repository, at
-  https://github.com/sphinx-doc/sphinx/.
-* Issues and feature requests should be raised in the `tracker
-  <https://github.com/sphinx-doc/sphinx/issues>`_.
-* The mailing list for development is at `Google Groups
-  <https://groups.google.com/forum/#!forum/sphinx-dev>`_.
-* There is also the #sphinx-doc IRC channel on `freenode
-  <https://freenode.net/>`_.
-
-For more about our development process and methods, refer to
-:doc:`/internals/index`.
-
-Extensions
-==========
-
-To learn how to write your own extension, see :ref:`dev-extensions`.
-
-The `sphinx-contrib <https://github.com/sphinx-contrib>`_ repository contains many
-contributed extensions.  Some of them have their own releases on PyPI, others you
-can install from a checkout.
-
-This is the current list of contributed extensions in that repository:
-
-- aafig: render embedded ASCII art as nice images using aafigure_
-- actdiag: embed activity diagrams by using actdiag_
-- adadomain: an extension for Ada support (Sphinx 1.0 needed)
-- ansi: parse ANSI color sequences inside documents
-- argdoc: automatically generate documentation for command-line arguments,
-  descriptions and help text
-- astah: embed diagram by using astah
-- autoanysrc: Gather reST documentation from any source files
-- autorun: Execute code in a ``runblock`` directive
-- beamer_: A builder for Beamer (LaTeX) output.
-- blockdiag: embed block diagrams by using blockdiag_
-- cacoo: embed diagram from Cacoo
-- cf3domain: a domain for CFEngine 3 policies
-- cheader: The missing c:header directive for Sphinx's built-in C domain
-- cheeseshop: easily link to PyPI packages
-- clearquest: create tables from ClearQuest_ queries
-- cmakedomain_: a domain for CMake_
-- coffeedomain: a domain for (auto)documenting CoffeeScript source code
-- context: a builder for ConTeXt
-- disqus: embed Disqus comments in documents
-- documentedlist: converts a Python list to a table in the generated
-  documentation
-- doxylink: Link to external Doxygen-generated HTML documentation
-- domaintools_: A tool for easy domain creation
-- email: obfuscate email addresses
-- erlangdomain: an extension for Erlang support (Sphinx 1.0 needed)
-- exceltable: embed Excel spreadsheets into documents using exceltable_
-- feed: an extension for creating syndication feeds and time-based overviews
-  from your site content
-- findanything_: an extension to add Sublime Text 2-like findanything panels
-  to your documentation to find pages, sections and index entries while typing
-- gnuplot: produces images using gnuplot_ language
-- googleanalytics: track web visitor statistics by using `Google Analytics`_
-- googlechart: embed charts by using `Google Chart`_
-- googlemaps: embed maps by using `Google Maps`_
-- httpdomain: a domain for documenting RESTful HTTP APIs
-- hyphenator: client-side hyphenation of HTML using hyphenator_
-- imgur: embed Imgur images, albums, and metadata in documents
-- inlinesyntaxhighlight_: inline syntax highlighting
-- lassodomain: a domain for documenting Lasso_ source code
-- libreoffice: an extension to include any drawing supported by LibreOffice
-  (e.g. odg, vsd, ...)
-- lilypond: an extension inserting music scripts from Lilypond_ in PNG format
-- makedomain_: a domain for `GNU Make`_
-- matlabdomain: document MATLAB_ code
-- mockautodoc: mock imports
-- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s
-- napoleon: supports `Google style`_ and `NumPy style`_ docstrings
-- nicovideo: embed videos from nicovideo
-- nwdiag: embed network diagrams by using nwdiag_
-- omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed)
-- osaka: convert standard Japanese doc to Osaka dialect (this is a joke
-  extension)
-- paverutils: an alternate integration of Sphinx with Paver_
-- phpdomain: an extension for PHP support
-- plantuml: embed UML diagram by using PlantUML_
-- py_directive: Execute python code in a ``py`` directive and return a math
-  node
-- rawfiles: copy raw files, like a CNAME
-- requirements: declare requirements wherever you need (e.g. in test
-  docstrings), mark statuses and collect them in a single list
-- restbuilder: a builder for reST (reStructuredText) files
-- rubydomain: an extension for Ruby support (Sphinx 1.0 needed)
-- sadisplay: display SqlAlchemy model sadisplay_
-- sdedit: an extension inserting sequence diagram by using Quick Sequence
-  Diagram Editor (sdedit_)
-- seqdiag: embed sequence diagrams by using seqdiag_
-- slide: embed presentation slides on slideshare_ and other sites
-- swf_: embed flash files
-- sword: an extension inserting Bible verses from Sword_
-- tikz: draw pictures with the `TikZ/PGF LaTeX package`_
-- traclinks: create TracLinks_ to a Trac_ instance from within Sphinx
-- versioning: Sphinx extension that allows building versioned docs for
-  self-hosting
-- whooshindex: whoosh indexer extension
-- youtube: embed videos from YouTube_
-- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_
-
-
-See the :doc:`extension tutorials <../development/tutorials/index>` on getting
-started with writing your own extensions.
-
-
-.. _aafigure: https://launchpad.net/aafigure
-.. _gnuplot: http://www.gnuplot.info/
-.. _paver: https://paver.readthedocs.io/en/latest/
-.. _Sword: https://www.crosswire.org/sword/
-.. _Lilypond: http://lilypond.org/
-.. _sdedit: http://sdedit.sourceforge.net/
-.. _Trac: https://trac.edgewall.org/
-.. _TracLinks: https://trac.edgewall.org/wiki/TracLinks
-.. _OmegaT: https://omegat.org/
-.. _PlantUML: http://plantuml.com/
-.. _PyEnchant: https://pythonhosted.org/pyenchant/
-.. _sadisplay: https://bitbucket.org/estin/sadisplay/wiki/Home
-.. _blockdiag: http://blockdiag.com/en/
-.. _seqdiag: http://blockdiag.com/en/
-.. _actdiag: http://blockdiag.com/en/
-.. _nwdiag: http://blockdiag.com/en/
-.. _Google Analytics: https://www.google.com/analytics/
-.. _Google Chart: https://developers.google.com/chart/
-.. _Google Maps: https://www.google.com/maps
-.. _Google style: https://google.github.io/styleguide/pyguide.html
-.. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
-.. _hyphenator: https://github.com/mnater/hyphenator
-.. _exceltable: https://pythonhosted.org/sphinxcontrib-exceltable/
-.. _YouTube: https://www.youtube.com/
-.. _ClearQuest: https://www.ibm.com/us-en/marketplace/rational-clearquest
-.. _Zope interfaces: https://zopeinterface.readthedocs.io/en/latest/README.html
-.. _slideshare: https://www.slideshare.net/
-.. _TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf/
-.. _MATLAB: https://www.mathworks.com/products/matlab.html
-.. _swf: https://github.com/sphinx-contrib/swf
-.. _findanything: https://github.com/sphinx-contrib/findanything
-.. _cmakedomain: https://github.com/sphinx-contrib/cmakedomain
-.. _GNU Make: https://www.gnu.org/software/make/
-.. _makedomain: https://github.com/sphinx-contrib/makedomain
-.. _inlinesyntaxhighlight: https://sphinxcontrib-inlinesyntaxhighlight.readthedocs.io/
-.. _CMake: https://cmake.org
-.. _domaintools: https://github.com/sphinx-contrib/domaintools
-.. _restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
-.. _Lasso: http://www.lassosoft.com/
-.. _beamer: https://pypi.org/project/sphinxcontrib-beamer/
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 3bb993f25..cc12e1eb1 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -560,7 +560,7 @@ General configuration
    * Otherwise, the current time is formatted using :func:`time.strftime` and
      the format given in :confval:`today_fmt`.
 
-   The default is now :confval:`today` and a :confval:`today_fmt` of ``'%B %d,
+   The default is now :confval:`today` and a :confval:`today_fmt` of ``'%b %d,
    %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent
    format for the selected locale).
 
diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst
index 3b9970173..3d076fb3a 100644
--- a/doc/usage/extensions/index.rst
+++ b/doc/usage/extensions/index.rst
@@ -41,22 +41,19 @@ These extensions are built in and can be activated by respective entries in the
 Third-party extensions
 ----------------------
 
-.. todo:: This should reference the GitHub organization now
-
-You can find several extensions contributed by users in the `Sphinx Contrib`_
-repository.  It is open for anyone who wants to maintain an extension publicly;
-just send a short message asking for write permissions.
-
-There are also several extensions hosted elsewhere.  The `Sphinx extension
-survey <https://sphinxext-survey.readthedocs.io/>`__ and `awesome-sphinxdoc
-<https://github.com/yoloseem/awesome-sphinxdoc>`__ contains a comprehensive
-list.
-
-If you write an extension that you think others will find useful or you think
-should be included as a part of Sphinx, please write to the project mailing
-list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
-
-.. _Sphinx Contrib: https://github.com/sphinx-contrib
+You can find several extensions contributed by users in the `sphinx-contrib`__
+organization. If you wish to include your extension in this organization,
+simply follow the instructions provided in the `github-administration`__
+project. This is optional and there are several extensions hosted elsewhere.
+The `awesome-sphinxdoc`__ project contains a curated list of Sphinx packages,
+and many packages use the ``Framework :: Sphinx :: Extension`` and
+``Framework :: Sphinx :: Theme`` `trove classifiers`__ for Sphinx extensions
+and themes, respectively.
+
+.. __: https://github.com/sphinx-contrib/
+.. __: https://github.com/sphinx-contrib/github-administration
+.. __: https://github.com/yoloseem/awesome-sphinxdoc
+.. __: https://pypi.org/classifiers/
 
 Where to put your own extensions?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/sphinx/application.py b/sphinx/application.py
index 51ef94d71..acc512694 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -399,9 +399,10 @@ class Sphinx:
     def require_sphinx(self, version: str) -> None:
         """Check the Sphinx version if requested.
 
-        Compare *version* (which must be a ``major.minor`` version string, e.g.
-        ``'1.1'``) with the version of the running Sphinx, and abort the build
-        when it is too old.
+        Compare *version* with the version of the running Sphinx, and abort the
+        build when it is too old.
+
+        :param version: The required version in the form of ``major.minor``.
 
         .. versionadded:: 1.0
         """
@@ -415,11 +416,11 @@ class Sphinx:
         For details on available core events and the arguments of callback
         functions, please see :ref:`events`.
 
-        Registered callbacks will be invoked on event in the order of *priority* and
-        registration.  The priority is ascending order.
-
-        The method returns a "listener ID" that can be used as an argument to
-        :meth:`disconnect`.
+        :param event: The name of target event
+        :param callback: Callback function for the event
+        :param priority: The priority of the callback.  The callbacks will be invoked
+                         in the order of *priority* in asending.
+        :return: A listener ID.  It can be used for :meth:`disconnect`.
 
         .. versionchanged:: 3.0
 
@@ -431,7 +432,10 @@ class Sphinx:
         return listener_id
 
     def disconnect(self, listener_id: int) -> None:
-        """Unregister callback by *listener_id*."""
+        """Unregister callback by *listener_id*.
+
+        :param listener_id: A listener_id that :meth:`connect` returns
+        """
         logger.debug('[app] disconnecting event: [id=%s]', listener_id)
         self.events.disconnect(listener_id)
 
@@ -442,6 +446,10 @@ class Sphinx:
         Return the return values of all callbacks as a list.  Do not emit core
         Sphinx events in extensions!
 
+        :param event: The name of event that will be emitted
+        :param args: The arguments for the event
+        :param allowed_exceptions: The list of exceptions that are allowed in the callbacks
+
         .. versionchanged:: 3.1
 
            Added *allowed_exceptions* to specify path-through exceptions
@@ -454,6 +462,10 @@ class Sphinx:
 
         Return the result of the first callback that doesn't return ``None``.
 
+        :param event: The name of event that will be emitted
+        :param args: The arguments for the event
+        :param allowed_exceptions: The list of exceptions that are allowed in the callbacks
+
         .. versionadded:: 0.5
         .. versionchanged:: 3.1
 
@@ -467,10 +479,9 @@ class Sphinx:
     def add_builder(self, builder: "Type[Builder]", override: bool = False) -> None:
         """Register a new builder.
 
-        *builder* must be a class that inherits from :class:`~sphinx.builders.Builder`.
-
-        If *override* is True, the given *builder* is forcedly installed even if
-        a builder having the same name is already installed.
+        :param builder: A builder class
+        :param override: If true, install the builder forcedly even if another builder
+                         is already installed as the same name
 
         .. versionchanged:: 1.8
            Add *override* keyword.
@@ -531,8 +542,10 @@ class Sphinx:
         builtin translator.  This allows extensions to use custom translator
         and define custom nodes for the translator (see :meth:`add_node`).
 
-        If *override* is True, the given *translator_class* is forcedly installed even if
-        a translator for *name* is already installed.
+        :param name: The name of builder for the translator
+        :param translator_class: A translator class
+        :param override: If true, install the translator forcedly even if another translator
+                         is already installed as the same name
 
         .. versionadded:: 1.3
         .. versionchanged:: 1.8
@@ -617,10 +630,10 @@ class Sphinx:
     def add_directive(self, name: str, cls: "Type[Directive]", override: bool = False) -> None:
         """Register a Docutils directive.
 
-        *name* must be the prospective directive name.  *cls* is a directive
-        class which inherits ``docutils.parsers.rst.Directive``.  For more
-        details, see `the Docutils docs
-        <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ .
+        :param name: The name of directive
+        :param cls: A directive class
+        :param override: If true, install the directive forcedly even if another directive
+                         is already installed as the same name
 
         For example, a custom directive named ``my-directive`` would be added
         like this:
@@ -645,8 +658,8 @@ class Sphinx:
            def setup(app):
                add_directive('my-directive', MyDirective)
 
-        If *override* is True, the given *cls* is forcedly installed even if
-        a directive named as *name* is already installed.
+        For more details, see `the Docutils docs
+        <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`__ .
 
         .. versionchanged:: 0.6
            Docutils 0.5-style directive classes are now supported.
@@ -665,13 +678,13 @@ class Sphinx:
     def add_role(self, name: str, role: Any, override: bool = False) -> None:
         """Register a Docutils role.
 
-        *name* must be the role name that occurs in the source, *role* the role
-        function. Refer to the `Docutils documentation
-        <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ for
-        more information.
+        :param name: The name of role
+        :param cls: A role function
+        :param override: If true, install the role forcedly even if another role is already
+                         installed as the same name
 
-        If *override* is True, the given *role* is forcedly installed even if
-        a role named as *name* is already installed.
+        For more details about role functions, see `the Docutils docs
+        <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`__ .
 
         .. versionchanged:: 1.8
            Add *override* keyword.