Merge branch 'master' into typos

Author: tk0miya

.github/workflows/main.yml

@@ -4,16 +4,12 @@ on: [push, pull_request]
 
 jobs:
   ubuntu:
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-18.04
     strategy:
       fail-fast: false
       matrix:
-        name: [py35, py36, py37, py38, py39]
-        os: [ubuntu-16.04]
+        name: [py36, py37, py38, py39, py310-dev]
         include:
-        - name: py35
-          python: 3.5
-          docutils: du12
         - name: py36
           python: 3.6
           docutils: du13
@@ -30,7 +26,6 @@ jobs:
         - name: py310-dev
           python: 3.10-dev
           docutils: du16
-          os: ubuntu-latest  # required
     env:
       PYTEST_ADDOPTS: ${{ matrix.coverage }}
 

CHANGES

@@ -1,3 +1,130 @@
+Release 4.0.0 (in development)
+==============================
+
+Dependencies
+------------
+
+* Drop python 3.5 support
+* Drop docutils 0.12 and 0.13 support
+* LaTeX: add ``tex-gyre`` font dependency
+
+Incompatible changes
+--------------------
+
+* domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate
+  methods that must be overrided in the concrete classes
+* #4826: py domain: The structure of python objects is changed.  A boolean value
+  is added to indicate that the python object is canonical one
+* #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom
+  MathJax configuration may have to set the old MathJax path or update their
+  configuration for version 3. See :mod:`sphinx.ext.mathjax`.
+* #7784: i18n: The msgid for alt text of image is changed
+* #5560: napoleon: :confval:`napoleon_use_param` also affect "other parameters"
+  section
+* #7996: manpage: Make a section directory on build manpage by default (see
+  :confval:`man_make_section_directory`)
+* #7849: html: Change the default setting of
+  :confval:`html_codeblock_linenos_style` to ``'inline'``
+* #8380: html search: search results are wrapped with ``<p>`` instead of
+  ``<div>``
+* html theme: Move a script tag for documentation_options.js in
+  basic/layout.html to ``script_files`` variable
+* html theme: Move CSS tags in basic/layout.html to ``css_files`` variable
+* #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
+* #8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese
+  documents
+* #5977: py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create
+  cross-references
+* #4550: The ``align`` attribute of ``figure`` and ``table`` nodes becomes
+  ``None`` by default instead of ``'default'``
+* #8769: LaTeX refactoring: split sphinx.sty into multiple files and rename
+  some auxiliary files created in ``latex`` build output repertory
+* #8937: Use explicit title instead of <no title>
+* #8487: The :file: option for csv-table directive now recognizes an absolute
+  path as a relative path from source directory
+
+Deprecated
+----------
+
+* :confval:`html_codeblock_linenos_style`
+* ``favicon`` and ``logo`` variable in HTML templates
+* ``sphinx.directives.patches.CSVTable``
+* ``sphinx.directives.patches.ListTable``
+* ``sphinx.directives.patches.RSTTable``
+* ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set``
+* ``sphinx.ext.autodoc.directive.DocumenterBridge.warn()``
+* ``sphinx.registry.SphinxComponentRegistry.get_source_input()``
+* ``sphinx.registry.SphinxComponentRegistry.source_inputs``
+* ``sphinx.transforms.FigureAligner``
+* ``sphinx.util.pycompat.convert_with_2to3()``
+* ``sphinx.util.pycompat.execfile_()``
+* ``sphinx.util.smartypants``
+* ``sphinx.util.typing.DirectiveOption``
+
+Features added
+--------------
+
+* #8924: autodoc: Support ``bound`` argument for TypeVar
+* #7383: autodoc: Support typehints for properties
+* #7549: autosummary: Enable :confval:`autosummary_generate` by default
+* #4826: py domain: Add ``:canonical:`` option to python directives to describe
+  the location where the object is defined
+* #7199: py domain: Add :confval:`python_use_unqualified_type_names` to suppress
+  the module name of the python reference if it can be resolved (experimental)
+* #7068: py domain: Add :rst:dir:`py:property` directive to describe a property
+* #7784: i18n: The alt text for image is translated by default (without
+  :confval:`gettext_additional_targets` setting)
+* #2018: html: :confval:`html_favicon` and :confval:`html_logo` now accept URL
+  for the image
+* #8070: html search: Support searching for 2characters word
+* #8938: imgconverter: Show the error of the command availability check
+* #7830: Add debug logs for change detection of sources and templates
+* #8201: Emit a warning if toctree contains duplicated entries
+* #8326: ``master_doc`` is now renamed to :confval:`root_doc`
+* #8942: C++, add support for the C++20 spaceship operator, ``<=>``.
+* #7199: A new node, ``sphinx.addnodes.pending_xref_condition`` has been added.
+  It can be used to choose appropriate content of the reference by conditions.
+
+Bugs fixed
+----------
+
+* #8917: autodoc: Raises a warning if function has wrong __globals__ value
+* #8415: autodoc: a TypeVar imported from other module is not resolved (in
+  Python 3.7 or above)
+* #8992: autodoc: Failed to resolve types.TracebackType type annotation
+* #8905: html: html_add_permalinks=None and html_add_permalinks="" are ignored
+* #8380: html search: Paragraphs in search results are not identified as ``<p>``
+* #8915: html theme: The translation of sphinx_rtd_theme does not work
+* #8342: Emit a warning if a unknown domain is given for directive or role (ex.
+  ``:unknown:doc:``)
+* #7241: LaTeX: No wrapping for ``cpp:enumerator``
+* #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning (and font
+  change) with late TeXLive 2019
+* #8253: LaTeX: Figures with no size defined get overscaled (compared to images
+  with size explicitly set in pixels) (fixed for ``'pdflatex'/'lualatex'`` only)
+* #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for navigation
+* #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output issues ignore
+  Pygments style
+* #8925: LaTeX: 3.5.0 ``verbatimmaxunderfull`` setting does not work as
+  expected
+* #8980: LaTeX: missing line break in ``\pysigline``
+* #8995: LaTeX: legacy ``\pysiglinewithargsret`` does not compute correctly
+  available  horizontal space and should use a ragged right style
+* #9009: LaTeX: "release" value with underscore leads to invalid LaTeX
+* #8911: C++: remove the longest matching prefix in
+  :confval:`cpp_index_common_prefix` instead of the first that matches.
+* C, properly reject function declarations when a keyword is used
+  as parameter name.
+* #8933: viewcode: Failed to create back-links on parallel build
+* #8960: C and C++, fix rendering of (member) function pointer types in
+  function parameter lists.
+* C++, fix linking of names in array declarators, pointer to member
+  (function) declarators, and in the argument to ``sizeof...``.
+* C, fix linking of names in array declarators.
+
+Testing
+--------
+
 Release 3.5.4 (in development)
 ==============================
 
@@ -100,6 +227,9 @@ Features added
 * #8775: autodoc: Support type union operator (PEP-604) in Python 3.10 or above
 * #8297: autodoc: Allow to extend :confval:`autodoc_default_options` via
   directive options
+* #759: autodoc: Add a new configuration :confval:`autodoc_preserve_defaults` as
+  an experimental feature.  It preserves the default argument values of
+  functions in source code and keep them not evaluated for readability.
 * #8619: html: kbd role generates customizable HTML tags for compound keys
 * #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
   for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`

EXAMPLES

@@ -12,19 +12,20 @@ interesting examples.
 Documentation using the alabaster theme
 ---------------------------------------
 
+* `AIOHTTP <https://docs.aiohttp.org/>`__
 * `Alabaster <https://alabaster.readthedocs.io/>`__
 * `Blinker <https://pythonhosted.org/blinker/>`__
 * `Calibre <https://manual.calibre-ebook.com/>`__
-* `Click <http://click.pocoo.org/>`__ (customized)
+* `Click <https://click.palletsprojects.com/>`__ (customized)
 * `coala <https://docs.coala.io/>`__ (customized)
 * `CodePy <https://documen.tician.de/codepy/>`__
 * `Eve <https://docs.python-eve.org/>`__ (Python REST API framework)
 * `Fabric <https://docs.fabfile.org/>`__
 * `Fityk <https://fityk.nieto.pl/>`__
-* `Flask <http://flask.pocoo.org/docs/>`__
+* `Flask <https://flask.palletsprojects.com/>`__
 * `Flask-OpenID <https://pythonhosted.org/Flask-OpenID/>`__
 * `Invoke <https://docs.pyinvoke.org/>`__
-* `Jinja <http://jinja.pocoo.org/docs/>`__
+* `Jinja <https://jinja.palletsprojects.com/>`__
 * `Lino <http://www.lino-framework.org/>`__ (customized)
 * `marbl <https://getmarbl.readthedocs.io/>`__
 * `MDAnalysis <https://www.mdanalysis.org/docs/>`__ (customized)
@@ -41,7 +42,8 @@ Documentation using the alabaster theme
 * `Spyder <https://docs.spyder-ide.org/>`__ (customized)
 * `Tablib <http://docs.python-tablib.org/>`__
 * `urllib3 <https://urllib3.readthedocs.io/>`__ (customized)
-* `Werkzeug <http://werkzeug.pocoo.org/docs/>`__ (customized)
+* `Werkzeug <https://werkzeug.palletsprojects.com/>`__
+* `Write the Docs <https://writethedocs-www.readthedocs.io/>`__
 
 Documentation using the classic theme
 -------------------------------------
@@ -132,7 +134,7 @@ Documentation using the sphinxdoc theme
 Documentation using the nature theme
 ------------------------------------
 
-* `Alembic <http://alembic.zzzcomputing.com/>`__
+* `Alembic <https://alembic.sqlalchemy.org/>`__
 * `Cython <http://docs.cython.org/>`__
 * `easybuild <https://easybuild.readthedocs.io/>`__
 * `jsFiddle <http://doc.jsfiddle.net/>`__
@@ -141,6 +143,7 @@ Documentation using the nature theme
 * `MapServer <https://mapserver.org/>`__ (customized)
 * `Pandas <https://pandas.pydata.org/pandas-docs/stable/>`__
 * `pyglet <https://pyglet.readthedocs.io/>`__ (customized)
+* `PyWavelets <https://pywavelets.readthedocs.io/>`__
 * `Setuptools <https://setuptools.readthedocs.io/>`__
 * `Spring Python <https://docs.spring.io/spring-python/1.2.x/sphinx/html/>`__
 * `StatsModels <https://www.statsmodels.org/>`__ (customized)
@@ -156,6 +159,7 @@ Documentation using another builtin theme
 * `PyPubSub <https://pypubsub.readthedocs.io/>`__ (bizstyle)
 * `Pylons <https://docs.pylonsproject.org/projects/pylons-webframework/>`__ (pyramid)
 * `Pyramid web framework <https://docs.pylonsproject.org/projects/pyramid/>`__ (pyramid)
+* `RxDock <https://www.rxdock.org/documentation/html/devel/>`__
 * `Sphinx <http://www.sphinx-doc.org/>`__ (sphinx13) :-)
 * `Valence <https://docs.valence.desire2learn.com/>`__ (haiku, customized)
 
@@ -219,6 +223,7 @@ Documentation using sphinx_rtd_theme
 * `Mailman <http://docs.list.org/>`__
 * `MathJax <https://docs.mathjax.org/>`__
 * `MDTraj <http://mdtraj.org/latest/>`__ (customized)
+* `Mesa 3D <https://docs.mesa3d.org/>`__
 * `micca - MICrobial Community Analysis <https://micca.readthedocs.io/>`__
 * `MicroPython <https://docs.micropython.org/>`__
 * `Minds <https://www.minds.org/docs/>`__ (customized)
@@ -227,6 +232,7 @@ Documentation using sphinx_rtd_theme
 * `mod_wsgi <https://modwsgi.readthedocs.io/>`__
 * `MoinMoin <https://moin-20.readthedocs.io/>`__
 * `Mopidy <https://docs.mopidy.com/>`__
+* `mpi4py <https://mpi4py.readthedocs.io/>`__
 * `MyHDL <http://docs.myhdl.org/>`__
 * `Nextflow <https://www.nextflow.io/docs/latest/index.html>`__
 * `NICOS <https://forge.frm2.tum.de/nicos/doc/nicos-master/>`__ (customized)
@@ -247,14 +253,15 @@ Documentation using sphinx_rtd_theme
 * `PyVISA <https://pyvisa.readthedocs.io/>`__
 * `pyvista <https://docs.pyvista.org/>`__
 * `Read The Docs <https://docs.readthedocs.io/>`__
+* `ROCm Platform <https://rocm-documentation.readthedocs.io/>`__
 * `Free your information from their silos (French) <http://redaction-technique.org/>`__ (customized)
 * `Releases Sphinx extension <https://releases.readthedocs.io/>`__
 * `Qtile <http://docs.qtile.org/>`__
 * `Quex <http://quex.sourceforge.net/doc/html/main.html>`__
 * `QuTiP <http://qutip.org/docs/latest/>`__
 * `Satchmo <http://docs.satchmoproject.com/>`__
 * `Scapy <https://scapy.readthedocs.io/>`__
-* `SimGrid <http://simgrid.gforge.inria.fr/simgrid/latest/doc/>`__
+* `SimGrid <https://simgrid.org/doc/latest/>`__
 * `SimPy <https://simpy.readthedocs.io/>`__
 * `six <https://six.readthedocs.io/>`__
 * `SlamData <https://newdocs.slamdata.com>`__
@@ -283,7 +290,6 @@ Documentation using sphinx_rtd_theme
 * `Web Application Attack and Audit Framework (w3af) <http://docs.w3af.org/>`__
 * `Weblate <https://docs.weblate.org/>`__
 * `x265 <https://x265.readthedocs.io/>`__
-* `ZeroNet <https://zeronet.readthedocs.io/>`__
 * `Zulip <https://zulip.readthedocs.io/>`__
 
 Documentation using sphinx_bootstrap_theme
@@ -319,6 +325,7 @@ Documentation using a custom theme or integrated in a website
 * `Doctrine <https://www.doctrine-project.org/>`__
 * `Enterprise Toolkit for Acrobat products <https://www.adobe.com/devnet-docs/acrobatetk/>`__
 * `FreeFEM <https://doc.freefem.org/introduction/>`__
+* `fmt <https://fmt.dev/>`__
 * `Gameduino <http://excamera.com/sphinx/gameduino/>`__
 * `gensim <https://radimrehurek.com/gensim/>`__
 * `GeoServer <http://docs.geoserver.org/>`__
@@ -328,6 +335,7 @@ Documentation using a custom theme or integrated in a website
 * `H2O.ai <http://docs.h2o.ai/>`__
 * `Heka <https://hekad.readthedocs.io/>`__
 * `Istihza (Turkish Python documentation project) <https://belgeler.yazbel.com/python-istihza/>`__
+* `JupyterHub <https://jupyterhub.readthedocs.io/>`__
 * `Kombu <http://docs.kombu.me/>`__
 * `Lasso <http://lassoguide.com/>`__
 * `Mako <http://docs.makotemplates.org/>`__

MANIFEST.in

@@ -15,6 +15,7 @@ include sphinx-quickstart.py
 include sphinx-apidoc.py
 include tox.ini
 include sphinx/locale/.tx/config
+include sphinx/py.typed
 
 recursive-include sphinx/templates *
 recursive-include sphinx/texinputs *

bindep.txt

@@ -12,10 +12,12 @@ texlive-luatex85 [platform:rpm]
 texlive-anyfontsize [platform:rpm]
 texlive-ctablestack [platform:rpm]
 texlive-gnu-freefont [platform:rpm]
+texlive-tex-gyre [platform:rpm]
 latexmk [platform:rpm]
 
 texlive-latex-recommended [platform:dpkg]
 texlive-fonts-recommended [platform:dpkg]
+tex-gyre [platform:dpkg]
 texlive-latex-extra [platform:dpkg]
 texlive-luatex [platform:dpkg]
 latexmk [platform:dpkg]

doc/_static/conf.py.txt

@@ -43,7 +43,7 @@ source_suffix = '.rst'
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+root_doc = 'index'
 
 # General information about the project.
 project = u'test'
@@ -252,7 +252,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'test.tex', u'test Documentation',
+    (root_doc, 'test.tex', u'test Documentation',
      u'test', 'manual'),
 ]
 
@@ -283,7 +283,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'test', u'test Documentation',
+    (root_doc, 'test', u'test Documentation',
      [author], 1)
 ]
 
@@ -298,7 +298,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'test', u'test Documentation',
+    (root_doc, 'test', u'test Documentation',
      author, 'test', 'One line description of project.',
      'Miscellaneous'),
 ]

doc/changes.rst

@@ -10,7 +10,6 @@ Changelog
 
 .. raw:: latex
 
-   \hypersetup{bookmarksdepth=1}% pdf bookmarks
    \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}%
 
 .. include:: ../CHANGES

doc/conf.py

@@ -9,7 +9,7 @@
               'sphinx.ext.intersphinx',
               'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram']
 
-master_doc = 'contents'
+root_doc = 'contents'
 templates_path = ['_templates']
 exclude_patterns = ['_build']
 
@@ -59,27 +59,14 @@
 latex_logo = '_static/sphinx.png'
 latex_elements = {
     'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
-    'fontpkg': r'''
-\usepackage[sc]{mathpazo}
-\usepackage[scaled]{helvet}
-\usepackage{courier}
-\substitutefont{LGR}{\rmdefault}{cmr}
-\substitutefont{LGR}{\sfdefault}{cmss}
-\substitutefont{LGR}{\ttdefault}{cmtt}
-\substitutefont{X2}{\rmdefault}{cmr}
-\substitutefont{X2}{\sfdefault}{cmss}
-\substitutefont{X2}{\ttdefault}{cmtt}
-''',
     'passoptionstopackages': r'''
 \PassOptionsToPackage{svgnames}{xcolor}
-\PassOptionsToPackage{bookmarksdepth=3}{hyperref}% depth of pdf bookmarks
 ''',
     'preamble': r'''
 \DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}}
-\setcounter{tocdepth}{3}%    depth of what is kept from toc file
+\setcounter{tocdepth}{3}%    depth of what main TOC shows (3=subsubsection)
 \setcounter{secnumdepth}{1}% depth of section numbering
 ''',
-    'fvset': '\\fvset{fontsize=auto}',
     # fix missing index entry due to RTD doing only once pdflatex after makeindex
     'printindex': r'''
 \IfFileExists{\jobname.ind}
@@ -91,6 +78,7 @@
 latex_use_xindy = True
 
 autodoc_member_order = 'groupwise'
+autosummary_generate = False
 todo_include_todos = True
 extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
                       'restructuredtext.html#%s', ''),