diff --git a/.flake8 b/.flake8 index 0f41face227..e01c0e5c803 100644 --- a/.flake8 +++ b/.flake8 @@ -29,4 +29,3 @@ exclude = doc/usage/extensions/example*.py, per-file-ignores = tests/*: E501 - sphinx/util/jsdump.py: SIM905 diff --git a/.github/workflows/builddoc.yml b/.github/workflows/builddoc.yml index 3b9609b7a12..83186ad4343 100644 --- a/.github/workflows/builddoc.yml +++ b/.github/workflows/builddoc.yml @@ -1,14 +1,20 @@ -name: Build document +name: Render documentation -on: [push, pull_request] +on: + push: + pull_request: + workflow_dispatch: permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true +env: + FORCE_COLOR: "1" + jobs: build: runs-on: ubuntu-latest @@ -27,10 +33,11 @@ jobs: python -m pip install .[docs] - name: Render the documentation run: > - python - -X dev - -X warn_default_encoding - -m sphinx + sphinx-build -M html ./doc ./build/sphinx + -T -W + --jobs=auto + -n + -vvv --keep-going diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml index 12ac825fb71..27971612f11 100644 --- a/.github/workflows/create-release.yml +++ b/.github/workflows/create-release.yml @@ -4,20 +4,87 @@ on: push: tags: - "v*.*.*" + workflow_dispatch: permissions: contents: read jobs: - create-release: + publish-pypi: + runs-on: ubuntu-latest + name: PyPI Release + environment: release permissions: - contents: write # for softprops/action-gh-release to create GitHub release + id-token: write # for PyPI trusted publishing + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3 + cache: pip + cache-dependency-path: pyproject.toml + + - name: Install build dependencies (pypa/build, twine) + run: | + pip install -U pip + pip install build twine + + - name: Build distribution + run: python -m build + + - name: Mint PyPI API token + id: mint-token + uses: actions/github-script@v6 + with: + # language=JavaScript + script: | + // retrieve the ambient OIDC token + const oidc_request_token = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN; + const oidc_request_url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL; + const oidc_resp = await fetch(`${oidc_request_url}&audience=pypi`, { + headers: {Authorization: `bearer ${oidc_request_token}`}, + }); + const oidc_token = (await oidc_resp.json()).value; + + // exchange the OIDC token for an API token + const mint_resp = await fetch('https://pypi.org/_/oidc/github/mint-token', { + method: 'post', + body: `{"token": "${oidc_token}"}` , + headers: {'Content-Type': 'application/json'}, + }); + const api_token = (await mint_resp.json()).token; + + // mask the newly minted API token, so that we don't accidentally leak it + core.setSecret(api_token) + core.setOutput('api-token', api_token) + + - name: Upload to PyPI + env: + TWINE_NON_INTERACTIVE: "true" + TWINE_USERNAME: "__token__" + TWINE_PASSWORD: "${{ steps.mint-token.outputs.api-token }}" + run: | + twine check dist/* + twine upload dist/* + + github-release: runs-on: ubuntu-latest + name: GitHub release + environment: release + permissions: + contents: write # for softprops/action-gh-release to create GitHub release steps: - - name: Checkout - uses: actions/checkout@v3 - - name: Release + - uses: actions/checkout@v3 + - name: Get release version + id: get_version + uses: actions/github-script@v6 + with: + script: core.setOutput('version', context.ref.replace("refs/tags/v", "")) + + - name: Create GitHub release uses: softprops/action-gh-release@v1 if: startsWith(github.ref, 'refs/tags/') with: + name: "Sphinx ${{ steps.get_version.outputs.version }}" body: "Changelog: https://www.sphinx-doc.org/en/master/changes.html" diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index 857a6ede8fd..1eaeccaa99a 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -6,7 +6,7 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index fb23ae1a927..963906e822c 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -6,7 +6,7 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true env: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 6468beb08f8..723aa472014 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -6,14 +6,14 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true env: FORCE_COLOR: "1" PYTHONDEVMODE: "1" # -X dev PYTHONWARNDEFAULTENCODING: "1" # -X warn_default_encoding - PYTHONWARNINGS: "error,always:unclosed:ResourceWarning" + PYTHONWARNINGS: "error" # default: all warnings as errors jobs: ubuntu: @@ -23,14 +23,15 @@ jobs: fail-fast: false matrix: python: - - "3.8" - "3.9" - "3.10" - "3.11" - "3.12-dev" + - "3.13-dev" docutils: - "0.18" - "0.19" + - "0.20" steps: - uses: actions/checkout@v3 @@ -57,11 +58,7 @@ jobs: env: PYTHONWARNINGS: "" - name: Install Docutils ${{ matrix.docutils }} - run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*" - if: "!endsWith(matrix.python, '-dev')" - - name: Install Docutils ${{ matrix.docutils }} (ignore warnings) - run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*" - if: "endsWith(matrix.python, '-dev')" + run: python -m pip install --upgrade "docutils~=${{ matrix.docutils }}.0" env: PYTHONWARNINGS: "" - name: Test with pytest diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index d021748578d..184d33211a3 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -6,7 +6,7 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.gitignore b/.gitignore index 8d33409d5bb..a2f7d63b3ad 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ doc/_build/ doc/locale/ tests/.coverage tests/build/ +tests/test-server.lock utils/regression_test.js node_modules/ diff --git a/AUTHORS b/AUTHORS index a35c27044f0..786d28c70be 100644 --- a/AUTHORS +++ b/AUTHORS @@ -93,12 +93,3 @@ Contributors * Zac Hatfield-Dodds -- doctest reporting improvements, intersphinx performance Many thanks for all contributions! - -Included software -================= - -There are also a few modules or functions incorporated from other -authors and projects: - -* sphinx.util.jsdump uses the basestring encoding from simplejson, - written by Bob Ippolito, released under the MIT license diff --git a/CHANGES b/CHANGES index 0097c68e74b..e74ec0e63e9 100644 --- a/CHANGES +++ b/CHANGES @@ -1,9 +1,197 @@ -Release 6.2.0 (in development) +Release 7.2.0 (in development) ============================== Dependencies ------------ +* #11511: Drop Python 3.8 support. + +Incompatible changes +-------------------- + +Deprecated +---------- + +* #11512: Deprecate ``sphinx.util.md5`` and ``sphinx.util.sha1``. + Use ``hashlib`` instead. +* #11526: Deprecate ``sphinx.testing.path``. + Use ``os.path`` or ``pathlib`` instead. + +Features added +-------------- + +* #11526: Support ``os.PathLike`` types and ``pathlib.Path`` objects + in many more places. + +Bugs fixed +---------- + +Testing +------- + +Release 7.1.1 (released Jul 27, 2023) +===================================== + +Bugs fixed +---------- + +* #11514: Fix ``SOURCE_DATE_EPOCH`` in multi-line copyright footer. + Patch by Bénédikt Tran. + +Release 7.1.0 (released Jul 24, 2023) +===================================== + +Incompatible changes +-------------------- + +* Releases are no longer signed, given the `change in PyPI policy`_. + + .. _change in PyPI policy: https://blog.pypi.org/posts/2023-05-23-removing-pgp/ + +Deprecated +---------- + +* #11412: Emit warnings on using a deprecated Python-specific index entry type + (namely, ``module``, ``keyword``, ``operator``, ``object``, ``exception``, + ``statement``, and ``builtin``) in the :rst:dir:`index` directive, and + set the removal version to Sphinx 9. Patch by Adam Turner. + +Features added +-------------- + +* #11415: Add a checksum to JavaScript and CSS asset URIs included within + generated HTML, using the CRC32 algorithm. +* :meth:`~sphinx.application.Sphinx.require_sphinx` now allows the version + requirement to be specified as ``(major, minor)``. +* #11011: Allow configuring a line-length limit for object signatures, via + :confval:`maximum_signature_line_length` and the domain-specific variants. + If the length of the signature (in characters) is greater than the configured + limit, each parameter in the signature will be split to its own logical line. + This behaviour may also be controlled by options on object description + directives, for example :rst:dir:`py:function:single-line-parameter-list`. + Patch by Thomas Louf, Adam Turner, and Jean-François B. +* #10983: Support for multiline copyright statements in the footer block. + Patch by Stefanie Molin +* ``sphinx.util.display.status_iterator`` now clears the current line + with ANSI control codes, rather than overprinting with space characters. +* #11431: linkcheck: Treat SSL failures as broken links. + Patch by Bénédikt Tran +* #11157: Keep the ``translated`` attribute on translated nodes. +* #11451: Improve the traceback displayed when using :option:`sphinx-build -T` + in parallel builds. Patch by Bénédikt Tran +* #11324: linkcheck: Use session-basd HTTP requests. +* #11438: Add support for the :rst:dir:`py:class` and :rst:dir:`py:function` + directives for PEP 695 (generic classes and functions declarations) and + PEP 696 (default type parameters). Multi-line support (#11011) is enabled + for type parameters list and can be locally controlled on object description + directives, e.g., :rst:dir:`py:function:single-line-type-parameter-list`. + Patch by Bénédikt Tran. +* #11484: linkcheck: Allow HTML anchors to be ignored on a per-URL basis + via :confval:`linkcheck_anchors_ignore_for_url` while + still checking the validity of the page itself. + Patch by Bénédikt Tran +* #1246: Add translation progress statistics and inspection support, + via a new substitution (``|translation progress|``) and a new + configuration variable (:confval:`translation_progress_classes`). + These enable determining the percentage of translated elements within + a document, and the remaining translated and untranslated elements. + +Bugs fixed +---------- + +* Restored the ``footnote-reference`` class that has been removed in + the latest (unreleased) version of Docutils. +* #11486: Use :rfc:`8081` font file MIME types in the EPUB builder. + Using the correct MIME type will prevent warnings from ``epubcheck`` + and will generate a valid EPUB. +* #11435: Use microsecond-resolution timestamps for outdated file detection + in ``BuildEnvironment.get_outdated_files``. +* #11437: Top-level headings starting with a reStructuredText role + now render properly when :confval:`rst_prolog` is set. + Previously, a file starting with the below would have + improperly rendered due to where the prologue text + was inserted into the document. + + .. code:: rst + + :mod:`lobster` -- The lobster module + ==================================== + + ... + + Patch by Bénédikt Tran. +* #11337: Fix a ``MemoryError`` in ``sphinx.ext.intersphinx`` when using ``None`` + or ``typing.*`` as inline type references. Patch by Bénédikt Tran (picnixz) + +Testing +------- + +* #11345: Always delete ``docutils.conf`` in test directories when running + ``SphinxTestApp.cleanup()``. + +Release 7.0.1 (released May 12, 2023) +===================================== + +Dependencies +------------ + +* #11411: Support `Docutils 0.20`_. Patch by Adam Turner. + +.. _Docutils 0.20: https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-20-2023-05-04 + +Bugs fixed +---------- + +* #11418: Clean up remaining references to ``sphinx.setup_command`` + following the removal of support for setuptools. + Patch by Willem Mulder. + +Release 7.0.0 (released Apr 29, 2023) +===================================== + +Incompatible changes +-------------------- + +* #11359: Remove long-deprecated aliases for ``MecabSplitter`` and + ``DefaultSplitter`` in ``sphinx.search.ja``. +* #11360: Remove deprecated ``make_old_id`` functions in domain object + description classes. +* #11363: Remove the Setuptools integration (``build_sphinx`` hook in + ``setup.py``). +* #11364: Remove deprecated ``sphinx.ext.napoleon.iterators`` module. +* #11365: Remove support for the ``jsdump`` format in ``sphinx.search``. +* #11366: Make ``locale`` a required argument to + ``sphinx.util.i18n.format_date()``. +* #11370: Remove deprecated ``sphinx.util.stemmer`` module. +* #11371: Remove deprecated ``sphinx.pycode.ast.parse()`` function. +* #11372: Remove deprecated ``sphinx.io.read_doc()`` function. +* #11373: Removed deprecated ``sphinx.util.get_matching_files()`` function. +* #11378: Remove deprecated ``sphinx.util.docutils.is_html5_writer_available()`` + function. +* #11379: Make the ``env`` argument to ``Builder`` subclasses required. +* #11380: autosummary: Always emit grouped import exceptions. +* #11381: Remove deprecated ``style`` key for HTML templates. +* #11382: Remove deprecated ``sphinx.writers.latex.LaTeXTranslator.docclasses`` + attribute. +* #11383: Remove deprecated ``sphinx.builders.html.html5_ready`` and + ``sphinx.builders.html.HTMLTranslator`` attributes. +* #11385: Remove support for HTML 4 output. + +Release 6.2.1 (released Apr 25, 2023) +===================================== + +Bugs fixed +---------- + +* #11355: Revert the default type of :confval:`nitpick_ignore` and + :confval:`nitpick_ignore_regex` to ``list``. + +Release 6.2.0 (released Apr 23, 2023) +===================================== + +Dependencies +------------ + * Require Docutils 0.18.1 or greater. Incompatible changes @@ -23,10 +211,13 @@ Deprecated ---------- * #11247: Deprecate the legacy ``intersphinx_mapping`` format +* ``sphinx.util.osutil.cd`` is deprecated in favour of ``contextlib.chdir``. Features added -------------- +* #11277: :rst:dir:`autoproperty` allows the return type to be specified as + a type comment (e.g., ``# type: () -> int``). Patch by Bénédikt Tran * #10811: Autosummary: extend ``__all__`` to imported members for template rendering when option ``autosummary_ignore_module_all`` is set to ``False``. Patch by Clement Pinard @@ -64,6 +255,9 @@ Bugs fixed * #11079: LaTeX: figures with align attribute may disappear and strangely impact following lists +* #11093: LaTeX: fix "multiply-defined references" PDF build warnings when one or + more reST labels directly precede an :rst:dir:`py:module` or :rst:dir:`automodule` + directive. Patch by Bénédikt Tran (picnixz) * #11110: LaTeX: Figures go missing from latex pdf if their files have the same base name and they use a post transform. Patch by aaron-cooper * LaTeX: fix potential color leak from shadow to border of rounded boxes, if @@ -74,6 +268,8 @@ Bugs fixed leak to the shadow and border at a page break * #11264: LaTeX: missing space before colon after "Voir aussi" for :rst:dir:`seealso` directive in French +* #11268: LaTeX: longtable with left alignment breaks out of current list + indentation context in PDF. Thanks to picnixz. * #11274: LaTeX: external links are not properly escaped for ``\sphinxupquote`` compatibility * #11147: Fix source file/line number info in object description content and in @@ -83,33 +279,12 @@ Bugs fixed * Use the new Transifex ``tx`` client Testing --------- +------- * Fail testing when any Python warnings are emitted * Migrate remaining ``unittest.TestCase`` style test functions to pytest style * Remove tests that rely on setuptools -Release 6.1.4 (in development) -============================== - -Dependencies ------------- - -Incompatible changes --------------------- - -Deprecated ----------- - -Features added --------------- - -Bugs fixed ----------- - -Testing --------- - Release 6.1.3 (released Jan 10, 2023) ===================================== @@ -487,7 +662,7 @@ Bugs fixed * #10498: gettext: TypeError is raised when sorting warning messages if a node has no line number. Patch by Adam Turner. -* #10493: HTML Theme: :rst:dir:`topic` directive is rendered incorrectly with +* #10493: HTML Theme: :dudir:`topic` directive is rendered incorrectly with Docutils 0.18. Patch by Adam Turner. * #10495: IndexError is raised for a :rst:role:`kbd` role having a separator. Patch by Adam Turner. @@ -591,7 +766,7 @@ Features added underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to EMCAScript 2018. Patch by Adam Turner. * #10302: C++, add support for conditional expressions (``?:``). -* #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role` +* #5157, #10251: Inline code is able to be highlighted via :dudir:`role` directive * #10337: Make sphinx-build faster by caching Publisher object during build. Patch by Adam Turner. @@ -914,7 +1089,7 @@ Bugs fixed * #9697: py domain: An index entry with parens was registered for ``py:method`` directive with ``:property:`` option * #9775: py domain: Literal typehint was converted to a cross reference when - :confval:`autodoc_typehints='description'` + :confval:`autodoc_typehints`\ ``='description'`` * #9708: needs_extension failed to check double-digit version correctly * #9688: Fix Sphinx patched :dudir:`code` does not recognize ``:class:`` option * #9733: Fix for logging handler flushing warnings in the middle of the docs @@ -1207,7 +1382,8 @@ Incompatible changes 4.0.0b1 * #8539: autodoc: info-field-list is generated into the class description when - ``autodoc_typehints='description'`` and ``autoclass_content='class'`` set + :confval:`autodoc_typehints`\ ``='description'`` and + :confval:`autoclass_content`\ ``='class'`` set * #8898: extlinks: "%s" becomes required keyword in the link caption string * domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate methods that must be overridden in the concrete classes @@ -1469,7 +1645,7 @@ Features added 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()` + for :meth:`.Sphinx.add_js_file()` and :meth:`.Sphinx.add_css_file()` * #6241: html: Allow to add JS/CSS files to the specific page when an extension calls ``app.add_js_file()`` or ``app.add_css_file()`` on :event:`html-page-context` event @@ -1483,7 +1659,7 @@ Features added * #8649: imgconverter: Skip availability check if builder supports the image type * #8573: napoleon: Allow to change the style of custom sections using - :confval:`napoleon_custom_styles` + :confval:`napoleon_custom_sections` * #8004: napoleon: Type definitions in Google style docstrings are rendered as references when :confval:`napoleon_preprocess_types` enabled * #6241: mathjax: Include mathjax.js only on the document using equations @@ -1670,7 +1846,7 @@ Features added messages when failed to resolve a cross-reference * #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference * #6629: linkcheck: The builder now handles rate limits. See - :confval:`linkcheck_retry_on_rate_limit` for details. + :confval:`linkcheck_rate_limit_timeout` for details. Bugs fixed ---------- @@ -1816,7 +1992,7 @@ Bugs fixed * #8320: make "inline" line numbers un-selectable Testing --------- +------- * #8257: Support parallel build in sphinx.testing @@ -1853,7 +2029,7 @@ Deprecated * ``sphinx.ext.autodoc.merge_special_members_option()`` * ``sphinx.writers.texinfo.TexinfoWriter.desc`` * C, parsing of pre-v3 style type directives and roles, along with the options - :confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`. + :confval:`!c_allow_pre_v3` and :confval:`!c_warn_on_allowed_pre_v3`. Features added -------------- @@ -1872,7 +2048,7 @@ Features added * #7690: napoleon: parse type strings and make them hyperlinks as possible. The conversion rule can be updated via :confval:`napoleon_type_aliases` * #8049: napoleon: Create a hyperlink for each the type of parameter when - :confval:`napoleon_use_params` is False + :confval:`napoleon_use_param` is False * C, added :rst:dir:`c:alias` directive for inserting copies of existing declarations. * #7745: html: inventory is broken if the docname contains a space @@ -1890,9 +2066,9 @@ Features added and the ``:noindex:`` option. * #7899: C, add possibility of parsing of some pre-v3 style type directives and roles and try to convert them to equivalent v3 directives/roles. - Set the new option :confval:`c_allow_pre_v3` to ``True`` to enable this. + Set the new option :confval:`!c_allow_pre_v3` to ``True`` to enable this. The warnings printed from this functionality can be suppressed by setting - :confval:`c_warn_on_allowed_pre_v3`` to ``True``. + :confval:`!c_warn_on_allowed_pre_v3` to ``True``. The functionality is immediately deprecated. * #7999: C, add support for named variadic macro arguments. * #8071: Allow to suppress "self referenced toctrees" warning @@ -1923,7 +2099,7 @@ Bugs fixed * #4258: napoleon: decorated special methods are not shown * #7799: napoleon: parameters are not escaped for combined params in numpydoc * #7780: napoleon: multiple parameters declaration in numpydoc was wrongly - recognized when napoleon_use_params=True + recognized when ``napoleon_use_param=True`` * #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links * #7846: html theme: XML-invalid files were generated * #7894: gettext: Wrong source info is shown when using rst_epilog @@ -2091,8 +2267,8 @@ Features added * C++, parse parameterized noexcept specifiers. * #7294: C++, parse expressions with user-defined literals. * C++, parse trailing return types. -* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class:`, - :rst:dir:`py:exception:` and :rst:dir:`py:method:` directives +* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class`, + :rst:dir:`py:exception` and :rst:dir:`py:method` directives * #7596: py domain: Change a type annotation for variables to a hyperlink * #7770: std domain: :rst:dir:`option` directive support arguments in the form of ``foo[=bar]`` @@ -2116,7 +2292,7 @@ Bugs fixed * #7559: autodoc: misdetects a sync function is async * #6857: autodoc: failed to detect a classmethod on Enum class * #7562: autodoc: a typehint contains spaces is wrongly rendered under - autodoc_typehints='description' mode + :confval:`autodoc_typehints`\ ``='description'`` mode * #7551: autodoc: failed to import nested class * #7362: autodoc: does not render correct signatures for built-in functions * #7654: autodoc: ``Optional[Union[foo, bar]]`` is presented as @@ -2219,7 +2395,7 @@ Release 3.0.1 (released Apr 11, 2020) Incompatible changes -------------------- -* #7418: std domain: :rst:dir:`term` role becomes case sensitive +* #7418: std domain: :rst:role:`term` role becomes case sensitive Bugs fixed ---------- @@ -2230,8 +2406,8 @@ Bugs fixed * #7418: std domain: duplication warning for glossary terms is case insensitive * #7438: C++, fix merging overloaded functions in parallel builds. * #7422: autodoc: fails with ValueError when using autodoc_mock_imports -* #7435: autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints - in signature for classes/methods +* #7435: autodoc: :confval:`autodoc_typehints`\ ``='description'`` doesn't + suppress typehints in signature for classes/methods * #7451: autodoc: fails with AttributeError when an object returns non-string object as a ``__doc__`` member * #7423: crashed when giving a non-string object to logger @@ -2642,7 +2818,7 @@ Features added authentication information when doing ``linkcheck`` builds * #6872: linkcheck: Handles HTTP 308 Permanent Redirect * #6613: html: Wrap section number in span tag -* #6781: gettext: Add :confval:`gettext_last_translator' and +* #6781: gettext: Add :confval:`gettext_last_translator` and :confval:`gettext_language_team` to customize headers of POT file Bugs fixed @@ -2781,7 +2957,7 @@ Bugs fixed since Sphinx 1.8.0 (refs: #6533) * #6531: Failed to load last environment object when extension added * #736: Invalid sort in pair index -* #6527: :confval:`last_updated` wrongly assumes timezone as UTC +* #6527: :data:`last_updated` wrongly assumes timezone as UTC * #5592: std domain: :rst:dir:`option` directive registers an index entry for each comma separated option * #6549: sphinx-build: Escaped characters in error messages @@ -2896,7 +3072,7 @@ Features added - ``PythonDomain.note_object()`` - ``SphinxDirective.set_source_info()`` -* #6180: Support ``--keep-going`` with BuildDoc setup command +* #6180: Support ``--keep-going`` with ``BuildDoc`` setup command * ``math`` directive now supports ``:class:`` option * todo: ``todo`` directive now supports ``:name:`` option * Enable override via environment of ``SPHINXOPTS`` and ``SPHINXBUILD`` Makefile @@ -2926,7 +3102,7 @@ Features added - ``:property:`` - ``:staticmethod:`` -* rst domain: Add :rst:dir:`directive:option` directive to describe the option +* rst domain: Add :rst:dir:`rst:directive:option` directive to describe the option for directive * #6306: html: Add a label to search form for accessability purposes * #4390: html: Consistent and semantic CSS for signatures @@ -2973,9 +3149,9 @@ Bugs fixed * RemovedInSphinx30Warning is marked as pending * deprecation warnings are not emitted - - sphinx.application.CONFIG_FILENAME - - sphinx.builders.htmlhelp - - :confval:`viewcode_import` + - ``sphinx.application.CONFIG_FILENAME`` + - ``sphinx.builders.htmlhelp`` + - :confval:`!viewcode_import` * #6208: C++, properly parse full xrefs that happen to have a short xref as prefix @@ -3263,7 +3439,7 @@ Bugs fixed * #6196: py domain: unexpected prefix is generated Testing --------- +------- 2.0.0b1 @@ -3458,7 +3634,7 @@ Incompatible changes 1.8.0b1 -* #5156: the :py:mod:`sphinx.ext.graphviz: extension runs `dot` in the +* #5156: the :py:mod:`sphinx.ext.graphviz` extension runs ``dot`` in the directory of the document being built instead of in the root directory of the documentation. * #4460: extensions which stores any data to environment should return the @@ -3483,7 +3659,7 @@ Incompatible changes * #4811: The files under :confval:`html_static_path` are excluded from source files. * latex: Use ``\sphinxcite`` for citation references instead ``\hyperref`` -* The config value ``viewcode_import`` is renamed to +* The config value :confval:`!viewcode_import` is renamed to :confval:`viewcode_follow_imported_members` (refs: #4035) * #1857: latex: :confval:`latex_show_pagerefs` does not add pagerefs for citations @@ -3524,7 +3700,7 @@ Deprecated * :confval:`autodoc_default_flags` is deprecated * quickstart: ``--epub`` option becomes default, so it is deprecated * Drop function based directive support. For now, Sphinx only supports class - based directives (see :class:`~Directive`) + based directives (see :class:`~docutils.parsers.rst.Directive`) * ``sphinx.util.docutils.directive_helper()`` is deprecated * ``sphinx.cmdline`` is deprecated * ``sphinx.make_mode`` is deprecated @@ -3596,8 +3772,7 @@ Deprecated * The ``trim_doctest_flags`` argument of ``sphinx.highlighting.PygmentsBridge`` is deprecated -For more details, see `deprecation APIs list -`_ +For more details, see :ref:`deprecation APIs list `. Features added -------------- @@ -3947,8 +4122,7 @@ Deprecated been changed (Since 1.7.0) * #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated. -For more details, see `deprecation APIs list -`_ +For more details, see :ref:`deprecation APIs list `. Bugs fixed ---------- @@ -4100,8 +4274,8 @@ Features removed * Configuration variables - - html_use_smartypants - - latex_keep_old_macro_names + - :confval:`!html_use_smartypants` + - :confval:`!latex_keep_old_macro_names` - latex_elements['footer'] * utility methods of ``sphinx.application.Sphinx`` class @@ -4179,7 +4353,7 @@ Bugs fixed Testing --------- +------- 1.7.0b1 @@ -4427,7 +4601,7 @@ Incompatible changes option and other options (refs: #3416) * LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine = 'lualatex'`` be used only on up-to-date TeX installs (refs #3070, #3466) -* :confval:`latex_keep_old_macro_names` default value has been changed from +* :confval:`!latex_keep_old_macro_names` default value has been changed from ``True`` to ``False``. This means that some LaTeX macros for styling are by default defined only with ``\sphinx..`` prefixed names. (refs: #3429) * Footer "Continued on next page" of LaTeX longtable's now not framed (refs: @@ -4633,8 +4807,8 @@ Deprecated * latex package ``footnote`` is not loaded anymore by its bundled replacement ``footnotehyper-sphinx``. The redefined macros keep the same names as in the original package. -* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be - removed at 1.7, and already its default value has changed from ``True`` to +* #3429: deprecate config setting :confval:`!latex_keep_old_macro_names`. It will + be removed at 1.7, and already its default value has changed from ``True`` to ``False``. * #3221: epub2 builder is deprecated * #3254: ``sphinx.websupport`` is now separated into independent package; @@ -4654,7 +4828,7 @@ Deprecated Please move customization into new macro ``\sphinxstyletheadfamily``. Testing --------- +------- 1.6 final @@ -4900,7 +5074,7 @@ Incompatible changes * Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even if ``epub_use_index = False``. * ``html_translator_class`` is now deprecated. - Use `Sphinx.set_translator()` API instead. + Use :meth:`~sphinx.application.Sphinx.set_translator` API instead. * Drop python 2.6 and 3.3 support * Drop epub3 builder's ``epub3_page_progression_direction`` option (use ``epub3_writing_mode``). @@ -5144,7 +5318,7 @@ Bugs fixed cannot be encoded into console encoding. Testing --------- +------- * To simplify, sphinx uses external mock package even if unittest.mock exists. @@ -5259,7 +5433,7 @@ Incompatible changes Features added -------------- -* new config option ``latex_keep_old_macro_names``, defaults to True. If False, +* new config option :confval:`!latex_keep_old_macro_names`, defaults to True. If False, lets macros (for text styling) be defined only with ``\sphinx``-prefixed names * latex writer allows user customization of "shadowed" boxes (topics), via three length variables. @@ -6647,7 +6821,8 @@ Features added * Other builders: - Added the Docutils-native XML and pseudo-XML builders. See - :class:`XMLBuilder` and :class:`PseudoXMLBuilder`. + :class:`~sphinx.builders.xml.XMLBuilder` and + :class:`~sphinx.builders.xml.PseudoXMLBuilder`. - PR#45: The linkcheck builder now checks ``#anchor``\ s for existence. - PR#123, #1106: Add `epub_use_index` configuration value. If provided, it will be used instead of `html_use_index` for epub @@ -6914,26 +7089,26 @@ Features added * Other builders: - - #516: Added new value of the `latex_show_urls` option to + - #516: Added new value of the :confval:`latex_show_urls` option to show the URLs in footnotes. - - #209: Added `text_newlines` and `text_sectionchars` + - #209: Added :confval:`text_newlines` and :confval:`text_sectionchars` config values. - - Added `man_show_urls` config value. + - Added :confval:`man_show_urls` config value. - #472: linkcheck builder: Check links in parallel, use HTTP HEAD requests and allow configuring the timeout. New config values: - `linkcheck_timeout` and `linkcheck_workers`. - - #521: Added `linkcheck_ignore` config value. + :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`. + - #521: Added :confval:`linkcheck_ignore` config value. - #28: Support row/colspans in tables in the LaTeX builder. * Configuration and extensibility: - - #537: Added `nitpick_ignore`. + - #537: Added :confval:`nitpick_ignore`. - #306: Added :event:`env-get-outdated` event. - - :meth:`.Application.add_stylesheet` now accepts full URIs. + - :meth:`!Application.add_stylesheet` now accepts full URIs. * Autodoc: - - #564: Add `autodoc_docstring_signature`. When enabled (the + - #564: Add :confval:`autodoc_docstring_signature`. When enabled (the default), autodoc retrieves the signature from the first line of the docstring, if it is found there. - #176: Provide ``private-members`` option for autodoc directives. @@ -7193,7 +7368,7 @@ Release 1.0.2 (Aug 14, 2010) ============================ * #490: Fix cross-references to objects of types added by the - :func:`~.Sphinx.add_object_type` API function. + :func:`~sphinx.application.Sphinx.add_object_type` API function. * Fix handling of doc field types for different directive types. @@ -7265,7 +7440,7 @@ Incompatible changes * The old markup for defining and linking to C directives is now deprecated. It will not work anymore in future versions without - activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx + activating the ``oldcmarkup`` extension; in Sphinx 1.0, it is activated by default. * Removed support for old dependency versions; requirements are now: @@ -7374,7 +7549,7 @@ Features added - Added `needs_sphinx` config value and :meth:`~sphinx.application.Sphinx.require_sphinx` application API method. - - #200: Added :meth:`~sphinx.application.Sphinx.add_stylesheet` + - #200: Added :meth:`!add_stylesheet` application API method. * Extensions: @@ -8028,7 +8203,7 @@ New features added - Highlighted code blocks now have CSS classes that make it possible to style them depending on their language. - - HTML ```` tags via the docutils ``meta`` directive are now + - HTML ```` tags via the docutils :dudir:`meta` directive are now supported. - ``SerializingHTMLBuilder`` was added as new abstract builder that diff --git a/EXAMPLES b/EXAMPLES index 53127983727..5a787c36aef 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -13,7 +13,7 @@ Documentation using the alabaster theme --------------------------------------- * `Alabaster `__ -* `Blinker `__ +* `Blinker `__ * `Calibre `__ * `CherryPy `__ * `Click `__ (customized) @@ -55,7 +55,6 @@ Documentation using the classic theme * `Apache CouchDB `__ (customized) * `APSW `__ * `Arb `__ -* `Bazaar `__ (customized) * `Beautiful Soup `__ * `Blender API `__ * `Bugzilla `__ @@ -66,7 +65,6 @@ Documentation using the classic theme * `DEAP `__ (customized) * `Director `__ * `EZ-Draw `__ (customized) -* `F2py `__ * `Generic Mapping Tools (GMT) `__ (customized) * `Genomedata `__ * `GetFEM++ `__ (customized) @@ -115,11 +113,10 @@ Documentation using the sphinxdoc theme * `ABRT `__ * `cartopy `__ -* `Jython `__ +* `Jython `__ * `LLVM `__ * `MDAnalysis Tutorial `__ * `PyCantonese `__ -* `PyRe `__ * `Pyre `__ * `pySPACE `__ * `Pysparse `__ @@ -150,18 +147,20 @@ Documentation using another builtin theme ----------------------------------------- * `Breathe `__ (haiku) +* `Breezy (fork of Bazaar) `__ (agogo) * `MPipe `__ (sphinx13) * `NLTK `__ (agogo) * `PyPubSub `__ (bizstyle) * `Pylons `__ (pyramid) * `Pyramid web framework `__ (pyramid) -* `RxDock `__ +* `RxDock `__ (bizstyle) * `Sphinx `__ (sphinx13) :-) * `Valence `__ (haiku, customized) Documentation using sphinx_rtd_theme ------------------------------------ +* `Aesara (fork of Theano) `__ * `Annotator `__ * `Ansible `__ (customized) * `Arcade `__ @@ -226,7 +225,7 @@ Documentation using sphinx_rtd_theme * `Linux kernel `__ * `Mailman `__ * `MathJax `__ -* `MDTraj `__ (customized) +* `MDTraj `__ (customized) * `Mesa 3D `__ * `micca - MICrobial Community Analysis `__ * `MicroPython `__ @@ -256,7 +255,6 @@ Documentation using sphinx_rtd_theme * `PHPUnit `__ * `PHPWord `__ * `PROS `__ (customized) -* `Pushkin `__ * `Pweave `__ * `pyca/cryptograhpy `__ * `PyNaCl `__ @@ -272,12 +270,10 @@ Documentation using sphinx_rtd_theme * `Qtile `__ * `Quex `__ * `QuTiP `__ -* `Satchmo `__ * `Scapy `__ * `SimGrid `__ * `SimPy `__ * `six `__ -* `SlamData `__ * `Solidity `__ * `Sonos Controller (SoCo) `__ * `Sphinx AutoAPI `__ @@ -289,11 +285,10 @@ Documentation using sphinx_rtd_theme * `StarUML `__ * `Sublime Text Unofficial Documentation `__ * `SunPy `__ -* `Sylius `__ +* `Sylius `__ * `Syncthing `__ * `Tango Controls `__ (customized) * `Topshelf `__ -* `Theano `__ * `ThreatConnect `__ * `TrueNAS `__ (customized) * `Tuleap `__ @@ -319,7 +314,6 @@ Documentation using sphinx_bootstrap_theme * `Hangfire `__ * `Hedge `__ * `ObsPy `__ -* `Open Dylan `__ * `OPNFV `__ * `Pootle `__ * `PyUblas `__ @@ -343,6 +337,7 @@ Documentation using pydata_sphinx_theme * `NetworkX `__ * `Numpy `__ * `Pandas `__ +* `Pystra (continuation of PyRe) `__ * `PyVista `__ * `SciPy `__ * `SEPAL `__ @@ -375,10 +370,10 @@ Documentation using a custom theme or integrated in a website * `Heka `__ * `Istihza (Turkish Python documentation project) `__ * `JupyterHub `__ -* `Kombu `__ -* `Lasso `__ +* `Kombu `__ +* `Lasso `__ * `Mako `__ -* `MirrorBrain `__ +* `MirrorBrain `__ * `Mitiq `__ * `MongoDB `__ * `Music21 `__ @@ -389,6 +384,7 @@ Documentation using a custom theme or integrated in a website * `ObjectListView `__ * `OpenERP `__ * `OpenCV `__ +* `Open Dylan `__ * `OpenLayers `__ * `OpenTURNS `__ * `Open vSwitch `__ @@ -401,7 +397,6 @@ Documentation using a custom theme or integrated in a website * `PyMOTW `__ * `python-aspectlib `__ (`sphinx_py3doc_enhanced_theme `__) * `QGIS `__ -* `qooxdoo `__ * `Roundup `__ * `SaltStack `__ * `scikit-learn `__ @@ -415,7 +410,6 @@ Documentation using a custom theme or integrated in a website * `tinyTiM `__ * `Twisted `__ * `Ubuntu Packaging Guide `__ -* `WebFaction `__ * `WTForms `__ Homepages and other non-documentation sites @@ -429,15 +423,14 @@ Homepages and other non-documentation sites * `Florian Diesch `__ * `Institute for the Design of Advanced Energy Systems (IDAES) `__ (sphinx_rtd_theme) * `IDAES Examples `__ (sphinx_rtd_theme) -* `Lei Ma's Statistical Mechanics lecture notes `__ (sphinx_bootstrap_theme) +* `Lei Ma's Statistical Mechanics lecture notes `__ (sphinx_bootstrap_theme) * `Loyola University Chicago CS Academic Programs `__ (sphinx_rtd_theme, customized) * `PyXLL `__ (sphinx_bootstrap_theme, customized) * `SciPy Cookbook `__ (sphinx_rtd_theme) -* `Tech writer at work blog `__ (custom theme) -* `The Wine Cellar Book `__ (sphinxdoc) +* `Tech writer at work blog `__ (custom theme) * `Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials `__ (standard) * `UC Berkeley ME233 Advanced Control Systems II course `__ (sphinxdoc) -* `Željko Svedružić's Biomolecular Structure and Function Laboratory (BioSFLab) `__ (sphinx_bootstrap_theme) +* `Željko Svedružić's Biomolecular Structure and Function Laboratory (BioSFLab) `__ (sphinx_bootstrap_theme) Books produced using Sphinx --------------------------- @@ -448,7 +441,7 @@ Books produced using Sphinx * `"Expert Python Programming" (Japanese translation) `__ * `"Expert Python Programming 2nd Edition" (Japanese translation) `__ * `"The Hitchhiker's Guide to Python" `__ -* `"LassoGuide" `__ +* `"LassoGuide" `__ * `"Learning Sphinx" (in Japanese) `__ * `"Learning System Programming with Go (Japanese)" `__ * `"Mercurial: the definitive guide (Second edition)" `__ @@ -472,8 +465,6 @@ Books produced using Sphinx Theses produced using Sphinx ---------------------------- -* `"A Web-Based System for Comparative Analysis of OpenStreetMap Data by the Use - of CouchDB" `__ * `"Content Conditioning and Distribution for Dynamic Virtual Worlds" `__ * `"The Sphinx Thesis Resource" `__ diff --git a/Makefile b/Makefile index 4602246d9cf..5293f6330ca 100644 --- a/Makefile +++ b/Makefile @@ -1,56 +1,43 @@ PYTHON ?= python3 .PHONY: all -all: clean-pyc clean-backupfiles style-check type-check test +all: style-check type-check test .PHONY: clean -clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles clean-mypyfiles - -.PHONY: clean-pyc -clean-pyc: +clean: clean + # clean Python cache files: find . -name '*.pyc' -exec rm -f {} + find . -name '*.pyo' -exec rm -f {} + - -.PHONY: clean-pycache -clean-pycache: find . -name __pycache__ -exec rm -rf {} + -.PHONY: clean-patchfiles -clean-patchfiles: - find . -name '*.orig' -exec rm -f {} + - find . -name '*.rej' -exec rm -f {} + - -.PHONY: clean-backupfiles -clean-backupfiles: + # clean backup files: find . -name '*~' -exec rm -f {} + find . -name '*.bak' -exec rm -f {} + find . -name '*.swp' -exec rm -f {} + find . -name '*.swo' -exec rm -f {} + -.PHONY: clean-generated -clean-generated: + # clean generated: find . -name '.DS_Store' -exec rm -f {} + - rm -rf Sphinx.egg-info/ - rm -rf dist/ + + # clean rendered documentation : + rm -rf doc/build/ rm -rf doc/_build/ - rm -f sphinx/pycode/*.pickle - rm -f utils/*3.py* - rm -f utils/regression_test.js + rm -rf build/sphinx/ -.PHONY: clean-testfiles -clean-testfiles: + # clean caches: + find . -name '.mypy_cache' -exec rm -rf {} + + find . -name '.ruff_cache' -exec rm -rf {} + + + # clean test files: rm -rf tests/.coverage rm -rf tests/build rm -rf .tox/ rm -rf .cache/ + find . -name '.pytest_cache' -exec rm -rf {} + -.PHONY: clean-buildfiles -clean-buildfiles: - rm -rf build - -.PHONY: clean-mypyfiles -clean-mypyfiles: - find . -name '.mypy_cache' -exec rm -rf {} + + # clean build files: + rm -rf dist/ + rm -rf build/ .PHONY: style-check style-check: diff --git a/README.rst b/README.rst index 277d17dfd31..d1ad3f4e34f 100644 --- a/README.rst +++ b/README.rst @@ -58,15 +58,6 @@ Contributing We appreciate all contributions! Refer to `the contributors guide`_ for information. -Release signatures -================== - -Releases are signed with following keys: - -* `498D6B9E `_ -* `5EBA0E07 `_ -* `61F0FB52 `_ - .. _the documentation: https://www.sphinx-doc.org/ .. _the contributors guide: https://www.sphinx-doc.org/en/master/internals/contributing.html .. _Python Package Index: https://pypi.org/project/Sphinx/ diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html index afab3693ba8..86a794306b9 100644 --- a/doc/_themes/sphinx13/layout.html +++ b/doc/_themes/sphinx13/layout.html @@ -32,7 +32,7 @@

{{ _('Navigation') }}

{%- block content %}