diff options
| -rw-r--r-- | doc/_templates/index.html | 6 | ||||
| -rw-r--r-- | doc/_themes/sphinx13/layout.html | 2 | ||||
| -rw-r--r-- | doc/develop.rst | 153 | ||||
| -rw-r--r-- | doc/usage/configuration.rst | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/index.rst | 29 | ||||
| -rw-r--r-- | sphinx/application.py | 67 |
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. |