diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 00000000000..18434754650 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,94 @@ +name: Bug report +description: Something is not working correctly. +labels: "bug" + +body: + - type: textarea + attributes: + label: Describe the bug + description: >- + A clear and concise description of what the bug is. + validations: + required: true + + - type: textarea + attributes: + label: How to Reproduce + description: Please provide steps to reproduce this bug. + value: | + + ``` + $ git clone https://github.com/.../some_project + $ cd some_project + $ pip install -r requirements.txt + $ cd docs + $ make html SPHINXOPTS="-D language=de" + $ # open _build/html/index and see bla bla + ``` + validations: + required: true + + - type: textarea + attributes: + label: Expected behavior + description: >- + A clear and concise description of what you expected to happen. + + - type: input + attributes: + label: Your project + description: >- + Link to your sphinx project, or attach zipped small project sample. + validations: + required: true + + - type: textarea + attributes: + label: Screenshots + description: >- + If applicable, add screenshots to help explain your problem. + validations: + required: false + + - type: markdown + attributes: + value: | + ## Environment info + + - type: input + attributes: + label: OS + description: >- + [e.g. Unix/Linux/Mac/Win/other with version] + validations: + required: true + - type: input + attributes: + label: Python version + validations: + required: true + - type: input + attributes: + label: Sphinx version + validations: + required: true + - type: input + attributes: + label: Sphinx extensions + description: >- + [e.g. sphinx.ext.autodoc, recommonmark] + validations: + required: false + - type: input + attributes: + label: Extra tools + description: >- + [e.g. Browser, tex or something else] + validations: + required: false + - type: textarea + attributes: + label: Additional context + description: >- + Add any other context about the problem here. + [e.g. URL or Ticket] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 0fa6b61fe73..00000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: 'bug' -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -``` - - -$ git clone https://github.com/.../some_project -$ cd some_project -$ pip install -r requirements.txt -$ cd docs -$ make html SPHINXOPTS="-D language=de" -$ # open _build/html/index and see bla bla -``` - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Your project** -Link to your sphinx project, or attach zipped small project sample. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Environment info** -- OS: [e.g. Unix/Linux/Mac/Win/other with version] -- Python version: [e.g. 3.7.1] -- Sphinx version: [e.g. 1.8.2] -- Sphinx extensions: [e.g. sphinx.ext.autodoc, recommonmark] -- Extra tools: [e.g. Browser, tex or something else] - -**Additional context** -Add any other context about the problem here. - -- [e.g. URL or Ticket] - diff --git a/.github/workflows/lock.yml b/.github/workflows/lock.yml new file mode 100644 index 00000000000..057e5a6f354 --- /dev/null +++ b/.github/workflows/lock.yml @@ -0,0 +1,19 @@ +name: 'Lock old threads' + +on: + schedule: + - cron: '0 0 * * *' + +permissions: + issues: write + pull-requests: write + +jobs: + action: + runs-on: ubuntu-latest + steps: + - uses: dessant/lock-threads@v2 + with: + github-token: ${{ github.token }} + issue-lock-inactive-days: '30' + pr-lock-inactive-days: '30' diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f3246857609..62a3d11394f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -23,9 +23,9 @@ jobs: python: 3.9 docutils: du17 coverage: "--cov ./ --cov-append --cov-config setup.cfg" - # - name: py310-dev - # python: 3.10-dev - # docutils: du16 + - name: py310-dev + python: 3.10-dev + docutils: du17 env: PYTEST_ADDOPTS: ${{ matrix.coverage }} diff --git a/.github/workflows/transifex.yml b/.github/workflows/transifex.yml new file mode 100644 index 00000000000..3efae8ff262 --- /dev/null +++ b/.github/workflows/transifex.yml @@ -0,0 +1,51 @@ +name: Sync translations on repository and transifex.com + +on: + schedule: + - cron: "0 0 * * SUN" + workflow_dispatch: + +jobs: + push: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + with: + ref: 4.x + - name: Set up Python + uses: actions/setup-python@v2 + - name: Install dependencies + run: pip install -U babel jinja2 transifex-client + - name: Extract translations from source code + run: python setup.py extract_messages + - name: Push translations to transifex.com + run: cd sphinx/locale && tx push -s --no-interactive --parallel + env: + TX_TOKEN: ${{ secrets.TX_TOKEN }} + + pull: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + with: + ref: 4.x + - name: Set up Python + uses: actions/setup-python@v2 + - name: Install dependencies + run: pip install -U babel jinja2 transifex-client + - name: Extract translations from source code + run: python setup.py extract_messages + - name: Pull translations to transifex.com + run: cd sphinx/locale && tx pull -a -f --no-interactive --parallel + env: + TX_TOKEN: ${{ secrets.TX_TOKEN }} + - name: Compile message catalogs + run: python setup.py compile_catalog + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + commit-message: 'Update message catalogs' + branch: bot/pull-translations + title: Update message catalogs diff --git a/CHANGES b/CHANGES index c91e5b95280..9cdf5ea3376 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,114 @@ +Release 4.1.0 (in development) +============================== + +Dependencies +------------ + +* Support jinja2-3.0 + +Incompatible changes +-------------------- + +Deprecated +---------- + +* The ``app`` argument of ``sphinx.environment.BuildEnvironment`` becomes + required +* ``sphinx.application.Sphinx.html_theme`` +* ``sphinx.ext.autosummary._app`` +* ``sphinx.util.docstrings.extract_metadata()`` + +Features added +-------------- + +* #8107: autodoc: Add ``class-doc-from`` option to :rst:dir:`autoclass` + directive to control the content of the specific class like + :confval:`autoclass_content` +* #8588: autodoc: :confval:`autodoc_type_aliases` now supports dotted name. It + allows you to define an alias for a class with module name like + ``foo.bar.BazClass`` +* #9175: autodoc: Special member is not documented in the module +* #9195: autodoc: The arguments of ``typing.Literal`` are wrongly rendered +* #9185: autodoc: :confval:`autodoc_typehints` allows ``'both'`` setting to + allow typehints to be included both in the signature and description +* #4257: autodoc: Add :confval:`autodoc_class_signature` to separate the class + entry and the definition of ``__init__()`` method +* #8061, #9218: autodoc: Support variable comment for alias classes +* #3014: autodoc: Add :event:`autodoc-process-bases` to modify the base classes + of the class definitions +* #9272: autodoc: Render enum values for the default argument value better +* #9384: autodoc: ``autodoc_typehints='none'`` now erases typehints for + variables, attributes and properties +* #3257: autosummary: Support instance attributes for classes +* #9358: html: Add "heading" role to the toctree items +* #9129: html search: Show search summaries when html_copy_source = False +* #9307: html search: Prevent corrections and completions in search field +* #9120: html theme: Eliminate prompt characters of code-block from copyable + text +* #9176: i18n: Emit a debug message if message catalog file not found under + :confval:`locale_dirs` +* #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese documents +* #9016: linkcheck: Support checking anchors on github.com +* #9016: linkcheck: Add a new event :event:`linkcheck-process-uri` to modify + URIs before checking hyperlinks +* #6525: linkcheck: Add :confval:`linkcheck_allowed_redirects` to mark + hyperlinks that are redirected to expected URLs as "working" +* #1874: py domain: Support union types using ``|`` in info-field-list +* #9268: py domain: :confval:`python_use_unqualified_type_names` supports type + field in info-field-list +* #9097: Optimize the parallel build +* #9131: Add :confval:`nitpick_ignore_regex` to ignore nitpicky warnings using + regular expressions +* #9174: Add ``Sphinx.set_html_assets_policy`` to tell extensions to include + HTML assets in all the pages. Extensions can check this via + ``Sphinx.registry.html_assets_policy`` +* C++, add support for + + - ``inline`` variables, + - ``consteval`` functions, + - ``constinit`` variables, + - ``char8_t``, + - ``explicit()`` specifier, + - digit separators in literals, and + - constraints in placeholder type specifiers, aka. adjective syntax + (e.g., ``Sortable auto &v``). + +* C, add support for digit separators in literals. +* #9166: LaTeX: support containers in LaTeX output + + +Bugs fixed +---------- + +* #8872: autodoc: stacked singledispatches are wrongly rendered +* #8597: autodoc: a docsting having metadata only should be treated as + undocumented +* #9185: autodoc: typehints for overloaded functions and methods are inaccurate +* #9250: autodoc: The inherited method not having docstring is wrongly parsed +* #9283: autodoc: autoattribute directive failed to generate document for an + attribute not having any comment +* #9364: autodoc: single element tuple on the default argument value is wrongly + rendered +* #9362: autodoc: AttributeError is raised on processing a subclass of Tuple[()] +* #9317: html: Pushing left key causes visiting the next page at the first page +* #9381: html: URL for html_favicon and html_log does not work +* #9270: html theme : pyramid theme generates incorrect logo links +* #9217: manpage: The name of manpage directory that is generated by + :confval:`man_make_section_directory` is not correct +* #9350: manpage: Fix font isn't reset after keyword at the top of samp role +* #9306: Linkcheck reports broken link when remote server closes the connection + on HEAD request +* #9280: py domain: "exceptions" module is not displayed +* #9319: quickstart: Make sphinx-quickstart exit when conf.py already exists +* #9387: xml: XML Builder ignores custom visitors +* #9224: ``:param:`` and ``:type:`` fields does not support a type containing + whitespace (ex. ``Dict[str, str]``) +* #8945: when transforming typed fields, call the specified role instead of + making an single xref. For C and C++, use the ``expr`` role for typed fields. + +Testing +-------- + Release 4.0.4 (in development) ============================== @@ -519,7 +630,7 @@ Bugs fixed * #8567: autodoc: Instance attributes are incorrectly added to Parent class * #8566: autodoc: The ``autodoc-process-docstring`` event is emitted to the alias classes unexpectedly -* #8583: autodoc: Unnecessary object comparision via ``__eq__`` method +* #8583: autodoc: Unnecessary object comparison via ``__eq__`` method * #8565: linkcheck: Fix PriorityQueue crash when link tuples are not comparable @@ -585,7 +696,7 @@ Bugs fixed * #8443: autodoc: autodata directive can't create document for PEP-526 based type annotated variables * #8443: autodoc: autoattribute directive can't create document for PEP-526 - based uninitalized variables + based uninitialized variables * #8480: autodoc: autoattribute could not create document for __slots__ attributes * #8503: autodoc: autoattribute could not create document for a GenericAlias as @@ -742,7 +853,7 @@ Bugs fixed * #8091: autodoc: AttributeError is raised on documenting an attribute on Python 3.5.2 * #8099: autodoc: NameError is raised when target code uses ``TYPE_CHECKING`` -* C++, fix parsing of template template paramters, broken by the fix of #7944 +* C++, fix parsing of template template parameters, broken by the fix of #7944 Release 3.2.0 (released Aug 08, 2020) ===================================== @@ -1031,7 +1142,7 @@ Bugs fixed * #3673: autodoc: member-order="bysource" does not work for a module having __all__ * #7668: autodoc: wrong retann value is passed to a handler of - autodoc-proccess-signature + autodoc-process-signature * #7711: autodoc: fails with ValueError when processing numpy objects * #7791: autodoc: TypeError is raised on documenting singledispatch function * #7551: autosummary: a nested class is indexed as non-nested class @@ -1237,7 +1348,7 @@ Features added * #6417: py domain: Allow to make a style for arguments of functions and methods * #7238, #7239: py domain: Emit a warning on describing a python object if the entry is already added as the same name -* #7341: py domain: type annotations in singature are converted to cross refs +* #7341: py domain: type annotations in signature are converted to cross refs * Support priority of event handlers. For more detail, see :py:meth:`.Sphinx.connect()` * #3077: Implement the scoping for :rst:dir:`productionlist` as indicated diff --git a/EXAMPLES b/EXAMPLES index 040637e9643..2942739b546 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -12,7 +12,6 @@ interesting examples. Documentation using the alabaster theme --------------------------------------- -* `AIOHTTP `__ * `Alabaster `__ * `Blinker `__ * `Calibre `__ @@ -26,14 +25,14 @@ Documentation using the alabaster theme * `Flask-OpenID `__ * `Invoke `__ * `Jinja `__ -* `Lino `__ (customized) +* `Lino `__ (customized) * `marbl `__ * `MDAnalysis `__ (customized) * `MeshPy `__ * `Molecule `__ * `PyCUDA `__ * `PyOpenCL `__ -* `PyLangAcq `__ +* `PyLangAcq `__ * `pytest `__ (customized) * `python-apt `__ * `PyVisfile `__ @@ -48,10 +47,10 @@ Documentation using the alabaster theme Documentation using the classic theme ------------------------------------- -* `Advanced Generic Widgets `__ (customized) -* `Apache CouchDB `__ (customized) +* `Advanced Generic Widgets `__ (customized) +* `Apache CouchDB `__ (customized) * `APSW `__ -* `Arb `__ +* `Arb `__ * `Bazaar `__ (customized) * `Beautiful Soup `__ * `Blender API `__ @@ -71,7 +70,7 @@ Documentation using the classic theme * `GetFEM++ `__ (customized) * `Glasgow Haskell Compiler `__ (customized) * `Grok `__ (customized) -* `GROMACS `__ +* `GROMACS `__ * `GSL Shell `__ * `Hands-on Python Tutorial `__ * `Kaa `__ (customized) @@ -79,9 +78,9 @@ Documentation using the classic theme * `LEPL `__ (customized) * `Mayavi `__ (customized) * `MediaGoblin `__ (customized) -* `mpmath `__ +* `mpmath `__ * `OpenCV `__ (customized) -* `OpenEXR `__ +* `OpenEXR `__ * `OpenGDA `__ * `Peach^3 `__ (customized) * `Plone `__ (customized) @@ -120,8 +119,8 @@ Documentation using the sphinxdoc theme * `Matplotlib `__ * `MDAnalysis Tutorial `__ * `NetworkX `__ -* `PyCantonese `__ -* `Pyre `__ +* `PyCantonese `__ +* `Pyre `__ * `pySPACE `__ * `Pysparse `__ * `PyTango `__ @@ -135,7 +134,7 @@ Documentation using the nature theme ------------------------------------ * `Alembic `__ -* `Cython `__ +* `Cython `__ * `easybuild `__ * `jsFiddle `__ * `libLAS `__ (customized) @@ -160,18 +159,19 @@ Documentation using another builtin theme * `Pylons `__ (pyramid) * `Pyramid web framework `__ (pyramid) * `RxDock `__ -* `Sphinx `__ (sphinx13) :-) +* `Sphinx `__ (sphinx13) :-) * `Valence `__ (haiku, customized) Documentation using sphinx_rtd_theme ------------------------------------ -* `Annotator `__ +* `Annotator `__ * `Ansible `__ (customized) -* `Arcade `__ +* `Arcade `__ * `aria2 `__ * `ASE `__ -* `Autofac `__ +* `asvin `__ +* `Autofac `__ * `BigchainDB `__ * `Blender Reference Manual `__ * `Blocks `__ @@ -189,28 +189,28 @@ Documentation using sphinx_rtd_theme * `DNF `__ * `Django-cas-ng `__ * `edX `__ -* `Electrum `__ -* `Elemental `__ +* `Electrum `__ +* `Elemental `__ * `ESWP3 `__ -* `Ethereum Homestead `__ +* `Ethereum Homestead `__ * `Exhale `__ * `Faker `__ * `Fidimag `__ -* `Flake8 `__ -* `Flatpak `__ +* `Flake8 `__ +* `Flatpak `__ * `FluidDyn `__ * `Fluidsim `__ * `Gallium `__ -* `GeoNode `__ +* `GeoNode `__ * `Glances `__ * `Godot `__ -* `Graylog `__ +* `Graylog `__ * `GPAW `__ (customized) -* `HDF5 for Python (h5py) `__ +* `HDF5 for Python (h5py) `__ * `Hyperledger Fabric `__ * `Hyperledger Sawtooth `__ -* `IdentityServer `__ -* `Idris `__ +* `IdentityServer `__ +* `Idris `__ * `javasphinx `__ * `Julia `__ * `Jupyter Notebook `__ @@ -220,45 +220,45 @@ Documentation using sphinx_rtd_theme * `LibCEED `__ * `Linguistica `__ * `Linux kernel `__ -* `Mailman `__ +* `Mailman `__ * `MathJax `__ * `MDTraj `__ (customized) * `Mesa 3D `__ * `micca - MICrobial Community Analysis `__ * `MicroPython `__ * `Minds `__ (customized) -* `Mink `__ -* `Mockery `__ +* `Mink `__ +* `Mockery `__ * `mod_wsgi `__ * `MoinMoin `__ * `Mopidy `__ * `mpi4py `__ -* `MyHDL `__ +* `MyHDL `__ * `Nextflow `__ * `NICOS `__ (customized) * `OpenFAST `__ -* `Pelican `__ +* `Pelican `__ * `picamera `__ * `Pillow `__ * `pip `__ * `Paver `__ -* `peewee `__ -* `Phinx `__ +* `peewee `__ +* `Phinx `__ * `phpMyAdmin `__ * `PROS `__ (customized) * `Pushkin `__ -* `Pweave `__ -* `PyPy `__ +* `Pweave `__ +* `PyPy `__ * `python-sqlparse `__ * `PyVISA `__ * `pyvista `__ * `Read The Docs `__ * `ROCm Platform `__ -* `Free your information from their silos (French) `__ (customized) +* `Free your information from their silos (French) `__ (customized) * `Releases Sphinx extension `__ -* `Qtile `__ +* `Qtile `__ * `Quex `__ -* `QuTiP `__ +* `QuTiP `__ * `Satchmo `__ * `Scapy `__ * `SimGrid `__ @@ -266,7 +266,7 @@ Documentation using sphinx_rtd_theme * `six `__ * `SlamData `__ * `Solidity `__ -* `Sonos Controller (SoCo) `__ +* `Sonos Controller (SoCo) `__ * `Sphinx AutoAPI `__ * `sphinx-argparse `__ * `Sphinx-Gallery `__ (customized) @@ -278,7 +278,7 @@ Documentation using sphinx_rtd_theme * `Sylius `__ * `Syncthing `__ * `Tango Controls `__ (customized) -* `Topshelf `__ +* `Topshelf `__ * `Theano `__ * `ThreatConnect `__ * `Tuleap `__ @@ -287,7 +287,7 @@ Documentation using sphinx_rtd_theme * `uWSGI `__ * `virtualenv `__ * `Wagtail `__ -* `Web Application Attack and Audit Framework (w3af) `__ +* `Web Application Attack and Audit Framework (w3af) `__ * `Weblate `__ * `x265 `__ * `Zulip `__ @@ -297,27 +297,28 @@ Documentation using sphinx_bootstrap_theme * `Bootstrap Theme `__ * `C/C++ Software Development with Eclipse `__ -* `Dataverse `__ +* `Dataverse `__ * `e-cidadania `__ -* `Hangfire `__ +* `Hangfire `__ * `Hedge `__ * `ObsPy `__ * `Open Dylan `__ * `OPNFV `__ -* `Pootle `__ +* `Pootle `__ * `PyUblas `__ * `seaborn `__ Documentation using a custom theme or integrated in a website ------------------------------------------------------------- +* `AIOHTTP `__ * `Apache Cassandra `__ -* `Astropy `__ +* `Astropy `__ * `Bokeh `__ * `Boto 3 `__ * `CakePHP `__ * `CasperJS `__ -* `Ceph `__ +* `Ceph `__ * `Chef `__ * `CKAN `__ * `Confluent Platform `__ @@ -326,24 +327,24 @@ Documentation using a custom theme or integrated in a website * `Enterprise Toolkit for Acrobat products `__ * `FreeFEM `__ * `fmt `__ -* `Gameduino `__ +* `Gameduino `__ * `gensim `__ -* `GeoServer `__ -* `gevent `__ +* `GeoServer `__ +* `gevent `__ * `GHC - Glasgow Haskell Compiler `__ -* `Guzzle `__ -* `H2O.ai `__ +* `Guzzle `__ +* `H2O.ai `__ * `Heka `__ * `Istihza (Turkish Python documentation project) `__ * `JupyterHub `__ * `Kombu `__ -* `Lasso `__ -* `Mako `__ -* `MirrorBrain `__ +* `Lasso `__ +* `Mako `__ +* `MirrorBrain `__ * `Mitiq `__ * `MongoDB `__ * `Music21 `__ -* `MyHDL `__ +* `MyHDL `__ * `ndnSIM `__ * `nose `__ * `ns-3 `__ @@ -353,30 +354,30 @@ Documentation using a custom theme or integrated in a website * `OpenCV `__ * `OpenLayers `__ * `OpenTURNS `__ -* `Open vSwitch `__ +* `Open vSwitch `__ * `PlatformIO `__ -* `PyEphem `__ -* `Pygments `__ +* `PyEphem `__ +* `Pygments `__ * `Plone User Manual (German) `__ -* `PSI4 `__ +* `PSI4 `__ * `PyMOTW `__ * `python-aspectlib `__ (`sphinx_py3doc_enhanced_theme `__) * `QGIS `__ * `qooxdoo `__ -* `Roundup `__ +* `Roundup `__ * `SaltStack `__ -* `scikit-learn `__ +* `scikit-learn `__ * `SciPy `__ * `Scrapy `__ * `Seaborn `__ * `Selenium `__ -* `Self `__ +* `Self `__ * `Substance D `__ -* `Sulu `__ +* `Sulu `__ * `SQLAlchemy `__ * `tinyTiM `__ * `Twisted `__ -* `Ubuntu Packaging Guide `__ +* `Ubuntu Packaging Guide `__ * `WebFaction `__ * `WTForms `__ @@ -387,7 +388,7 @@ Homepages and other non-documentation sites * `Benoit Boissinot `__ (classic, customized) * `Computer Networks, Parallelization, and Simulation Laboratory (CNPSLab) `__ (sphinx_rtd_theme) * `Deep Learning Tutorials `__ (sphinxdoc) -* `Eric Holscher `__ (alabaster) +* `Eric Holscher `__ (alabaster) * `Lei Ma's Statistical Mechanics lecture notes `__ (sphinx_bootstrap_theme) * `Loyola University Chicago COMP 339-439 Distributed Systems course `__ (sphinx_bootstrap_theme) * `Pylearn2 `__ (sphinxdoc, customized) @@ -408,7 +409,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)" `__ @@ -416,7 +417,7 @@ Books produced using Sphinx * `"Pioneers and Prominent Men of Utah" `__ * `"Pomodoro Technique Illustrated" (Japanese translation) `__ * `"Professional Software Development" `__ -* `"Python Professional Programming" (in Japanese) `__ +* `"Python Professional Programming" (in Japanese) `__ * `"Python Professional Programming 2nd Edition" (in Japanese) `__ * `"Python Professional Programming 3rd Edition" (in Japanese) `__ * `Python Course by Yuri Petrov (Russian) `__ diff --git a/README.rst b/README.rst index 13bbab99dbe..c60e58780be 100644 --- a/README.rst +++ b/README.rst @@ -10,10 +10,6 @@ :target: http://www.sphinx-doc.org/ :alt: Documentation Status -.. image:: https://travis-ci.org/sphinx-doc/sphinx.svg?branch=master - :target: https://travis-ci.org/sphinx-doc/sphinx - :alt: Build Status (Travis CI) - .. image:: https://ci.appveyor.com/api/projects/status/github/sphinx-doc/sphinx?branch=master&svg=true :target: https://ci.appveyor.com/project/sphinxdoc/sphinx :alt: Build Status (AppVeyor) diff --git a/babel.cfg b/babel.cfg index d41d26ad0ee..b1816e80d21 100644 --- a/babel.cfg +++ b/babel.cfg @@ -1,7 +1,7 @@ # How to setup this file -# http://babel.pocoo.org/en/latest/installation.html +# https://babel.pocoo.org/en/latest/installation.html # this file description: -# http://babel.pocoo.org/en/latest/messages.html +# https://babel.pocoo.org/en/latest/messages.html # Extraction from Python source files [python: **.py] diff --git a/doc/_static/tutorial/lumache-first-light.png b/doc/_static/tutorial/lumache-first-light.png new file mode 100644 index 00000000000..fbf4aec8a3e Binary files /dev/null and b/doc/_static/tutorial/lumache-first-light.png differ diff --git a/doc/_static/tutorial/lumache-furo.png b/doc/_static/tutorial/lumache-furo.png new file mode 100644 index 00000000000..c7aaee796cb Binary files /dev/null and b/doc/_static/tutorial/lumache-furo.png differ diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 9e9f7af56ff..eb2037447a2 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -29,19 +29,19 @@

{{ _('Welcome') }}

  • {%trans%}Automatic indices: general index as well as a language-specific module indices{%endtrans%}
  • {%trans%}Code handling: automatic highlighting using the Pygments highlighter{%endtrans%}
    • + href="https://pygments.org">Pygments highlighter{%endtrans%}
  • {%trans path=pathto('ext/builtins')%}Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more{%endtrans%}
    • -
  • {%trans path=pathto("usage/extensions")%}Contributed extensions: dozens of +
  • {%trans path=pathto("usage/extensions/index")%}Contributed extensions: dozens of extensions contributed by users; most of them installable from PyPI{%endtrans%}

    • {%trans%} - Sphinx uses reStructuredText + Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating - suite, the Docutils.{%endtrans%} + suite, the Docutils.{%endtrans%}

    {%trans%}Documentation{%endtrans%}

    @@ -52,23 +52,25 @@

    {%trans%}Documentation{%endtrans%}

    {%trans%}First steps with Sphinx{%endtrans%}
    {%trans%}overview of basic tasks{%endtrans%}

    - {%- if hasdoc('search') %}

    {%trans%}Search page{%endtrans%}
    - {%trans%}search the documentation{%endtrans%}

    {%- endif %} +

    {%trans%}Tutorial{%endtrans%}
    + {%trans%}beginners tutorial{%endtrans%}

    {%trans%}Contents{%endtrans%}
    {%trans%}for a complete overview{%endtrans%}

    - {%- if hasdoc('genindex') %}

    {%trans%}General Index{%endtrans%}
    - {%trans%}all functions, classes, terms{%endtrans%}

    {%- endif %} + {%- if hasdoc('search') %}

    {%trans%}Search page{%endtrans%}
    + {%trans%}search the documentation{%endtrans%}

    {%- endif %}

    {%trans%}Changes{%endtrans%}
    {%trans%}release history{%endtrans%}

    - + {%- if hasdoc('genindex') %}

    {%trans%}General Index{%endtrans%}
    + {%trans%}all functions, classes, terms{%endtrans%}

    {%- endif %} + diff --git a/doc/conf.py b/doc/conf.py index 3eb01b5eace..add9e8d6158 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,7 +35,7 @@ epub_theme = 'epub' epub_basename = 'sphinx' epub_author = 'Georg Brandl' -epub_publisher = 'http://sphinx-doc.org/' +epub_publisher = 'https://sphinx-doc.org/' epub_uid = 'web-site' epub_scheme = 'url' epub_identifier = epub_publisher @@ -80,11 +80,11 @@ autodoc_member_order = 'groupwise' autosummary_generate = False todo_include_todos = True -extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/' +extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/' 'restructuredtext.html#%s', ''), - 'durole': ('http://docutils.sourceforge.net/docs/ref/rst/' + 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/' 'roles.html#%s', ''), - 'dudir': ('http://docutils.sourceforge.net/docs/ref/rst/' + 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/' 'directives.html#%s', '')} man_pages = [ diff --git a/doc/contents.rst b/doc/contents.rst index eb694629244..21a27e233cb 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -7,6 +7,7 @@ Sphinx documentation contents :maxdepth: 2 usage/index + tutorial/index development/index man/index diff --git a/doc/development/theming.rst b/doc/development/theming.rst index 5de10158ae4..a63a1d668e8 100644 --- a/doc/development/theming.rst +++ b/doc/development/theming.rst @@ -207,9 +207,9 @@ inside your module: First, define the registration function, which accepts the arguments for :event:`html-page-context`. -Within the registration function, define the template function that you'd like to use -within Jinja. The template function should return a string or Python objects (lists, -dictionaries) with strings inside that Jinja uses in the templating process +Within the registration function, define the template function that you'd like to +use within Jinja. The template function should return a string or Python objects +(lists, dictionaries) with strings inside that Jinja uses in the templating process .. note:: @@ -256,6 +256,9 @@ Here is some sample code to accomplish this: .. code-block:: python + from os import path + from sphinx.util.fileutil import copy_asset_file + def copy_custom_files(app, exc): if app.builder.format == 'html' and not exc: staticdir = path.join(app.builder.outdir, '_static') diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst index 6eae5d6a3a5..2273330f14a 100644 --- a/doc/development/tutorials/helloworld.rst +++ b/doc/development/tutorials/helloworld.rst @@ -181,9 +181,9 @@ This is the very basic principle of an extension that creates a new directive. For a more advanced example, refer to :doc:`todo`. -.. _docutils: http://docutils.sourceforge.net/ -.. _docutils directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html -.. _docutils nodes: http://docutils.sourceforge.net/docs/ref/doctree.html +.. _docutils: https://docutils.sourceforge.io/ +.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html +.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html .. _PyPI: https://pypi.org/ .. _Python package: https://packaging.python.org/ .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst index 404be542fff..0e96a45cb1b 100644 --- a/doc/development/tutorials/recipe.rst +++ b/doc/development/tutorials/recipe.rst @@ -223,4 +223,4 @@ Further reading For more information, refer to the `docutils`_ documentation and :doc:`/extdev/index`. -.. _docutils: http://docutils.sourceforge.net/docs/ +.. _docutils: https://docutils.sourceforge.io/docs/ diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst index 21d9e74bead..c0a5c0d87e8 100644 --- a/doc/development/tutorials/todo.rst +++ b/doc/development/tutorials/todo.rst @@ -105,7 +105,7 @@ is just a "general" node. Many extensions will not have to create their own node classes and work fine with the nodes already provided by `docutils - `__ and :ref:`Sphinx + `__ and :ref:`Sphinx `. .. attention:: @@ -362,6 +362,6 @@ For more information, refer to the `docutils`_ documentation and :doc:`/extdev/index`. -.. _docutils: http://docutils.sourceforge.net/docs/ +.. _docutils: https://docutils.sourceforge.io/docs/ .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH -.. _docutils documentation: http://docutils.sourceforge.net/docs/ref/rst/directives.html +.. _docutils documentation: https://docutils.sourceforge.io/docs/ref/rst/directives.html diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 41318e9d62b..7c331382c65 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -159,7 +159,9 @@ connect handlers to the events. Example: Below is an overview of each event that happens during a build. In the list below, we include the event name, its callback parameters, and the input and output -type for that event:: +type for that event: + +.. code-block:: none 1. event.config-inited(app,config) 2. event.builder-inited(app) @@ -168,7 +170,7 @@ type for that event:: for docname in docnames: 5. event.env-purge-doc(app, env, docname) - + if doc changed and not removed: 6. source-read(app, docname, source) 7. run source parsers: text -> docutils.document @@ -176,10 +178,10 @@ type for that event:: 8. apply transforms based on priority: docutils.document -> docutils.document - event.doctree-read(app, doctree) is called in the middle of transforms, transforms come before/after this event depending on their priority. - + 9. event.env-merge-info(app, env, docnames, other) - if running in parallel mode, this event will be emitted for each process - + 10. event.env-updated(app, env) 11. event.env-get-updated(app, env) 12. event.env-check-consistency(app, env) @@ -377,13 +379,22 @@ Here is a more detailed list of these events. ``'page.html'`` as the HTML template for this page. .. note:: You can install JS/CSS files for the specific page via - :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since v3.5.0. + :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since + v3.5.0. .. versionadded:: 0.4 .. versionchanged:: 1.3 The return value can now specify a template name. +.. event:: linkcheck-process-uri (app, uri) + + Emitted when the linkcheck builder collects hyperlinks from document. *uri* + is a collected URI. The event handlers can modify the URI by returning a + string. + + .. versionadded:: 4.1 + .. event:: build-finished (app, exception) Emitted when a build has finished, before Sphinx exits, usually used for diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index e37c2b2ba4b..bca49370b35 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -22,6 +22,26 @@ The following is a list of deprecated interfaces. - (will be) Removed - Alternatives + * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment`` + - 4.1 + - 6.0 + - The required argument + + * - ``sphinx.application.Sphinx.html_theme`` + - 4.1 + - 6.0 + - ``sphinx.registry.SphinxComponentRegistry.html_themes`` + + * - ``sphinx.ext.autosummary._app`` + - 4.1 + - 6.0 + - N/A + + * - ``sphinx.util.docstrings.extract_metadata()`` + - 4.1 + - 6.0 + - ``sphinx.util.docstrings.separate_metadata()`` + * - ``favicon`` variable in HTML templates - 4.0 - TBD @@ -35,12 +55,12 @@ The following is a list of deprecated interfaces. * - ``sphinx.directives.patches.ListTable`` - 4.0 - 6.0 - - ``docutils.parsers.rst.diretives.tables.ListSVTable`` + - ``docutils.parsers.rst.directives.tables.ListSVTable`` * - ``sphinx.directives.patches.RSTTable`` - 4.0 - 6.0 - - ``docutils.parsers.rst.diretives.tables.RSTTable`` + - ``docutils.parsers.rst.directives.tables.RSTTable`` * - ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set`` - 4.0 @@ -80,7 +100,7 @@ The following is a list of deprecated interfaces. * - ``sphinx.util.smartypants`` - 4.0 - 6.0 - - ``docutils.utils.smartyquotes`` + - ``docutils.utils.smartquotes`` * - ``sphinx.util.typing.DirectiveOption`` - 4.0 @@ -730,8 +750,9 @@ The following is a list of deprecated interfaces. * - ``sphinx.environment.NoUri`` - 2.1 - - 4.0 + - 3.0 - ``sphinx.errors.NoUri`` + * - ``sphinx.ext.apidoc.format_directive()`` - 2.1 - 4.0 diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst index 75ef36cc51c..6b32b8b736a 100644 --- a/doc/extdev/i18n.rst +++ b/doc/extdev/i18n.rst @@ -94,4 +94,4 @@ message catalog template and message catalogs, for example via `Babel`_: $ pybabel extract --output=src/locale/myextension.pot src/ $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale -.. _Babel: http://babel.pocoo.org/ +.. _Babel: https://babel.pocoo.org/ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index d9c04f413d3..ffe8bc1362b 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -112,7 +112,7 @@ in which a Sphinx project is built: this works in several phases. existing files are read, temporary nodes are created. There are nodes provided by docutils, which are documented `in the docutils - documentation `__. + documentation `__. Additional nodes are provided by Sphinx and :ref:`documented here `. During reading, the build environment is updated with all meta- and cross @@ -175,7 +175,7 @@ as metadata of the extension. Metadata keys currently recognized are: .. note:: The *parallel-read-safe* extension must satisfy the following conditions: - * The core logic of the extension is parallely executable during + * The core logic of the extension is parallelly executable during the reading phase. * It has event handlers for :event:`env-merge-info` and :event:`env-purge-doc` events if it stores dataa to the build @@ -188,7 +188,7 @@ as metadata of the extension. Metadata keys currently recognized are: .. note:: The *parallel-write-safe* extension must satisfy the following conditions: - * The core logic of the extension is parallely executable during + * The core logic of the extension is parallelly executable during the writing phase. diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst index 7a21f812687..8fc884d7c71 100644 --- a/doc/extdev/markupapi.rst +++ b/doc/extdev/markupapi.rst @@ -149,4 +149,4 @@ return ``node.children`` from the Directive. `Creating directives`_ HOWTO of the Docutils documentation -.. _Creating directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html +.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst index 0beb5171191..1bd03fd0952 100644 --- a/doc/extdev/parserapi.rst +++ b/doc/extdev/parserapi.rst @@ -8,7 +8,7 @@ Parser API The Parser analyzes the input document and creates a node tree representation. -__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document +__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document In Sphinx, the parser modules works as same as docutils. The parsers are registered to Sphinx by extensions using Application APIs; diff --git a/doc/faq.rst b/doc/faq.rst index 49723d13480..4b273023d3a 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -145,7 +145,7 @@ Google Search .. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html .. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py -.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py +.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py Sphinx vs. Docutils @@ -179,10 +179,10 @@ of the *writers* provided by docutils. This allows Sphinx to provide many features that would simply not be possible with docutils, such as those outlined above. -__ http://docutils.sourceforge.io/ -__ http://docutils.sourceforge.io/docs/dev/hacking.html -__ http://docutils.sourceforge.io/rst.html -__ http://docutils.sourceforge.net/docs/user/tools.html +__ https://docutils.sourceforge.io/ +__ https://docutils.sourceforge.io/docs/dev/hacking.html +__ https://docutils.sourceforge.io/rst.html +__ https://docutils.sourceforge.io/docs/user/tools.html .. _epub-faq: @@ -259,7 +259,9 @@ The following list gives some hints for the creation of epub files: ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml`` - If you get the following error, fix your document structure:: + If you get the following error, fix your document structure: + + .. code-block:: none Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title) Error(prcgen):E24001: The table of content could not be built. diff --git a/doc/glossary.rst b/doc/glossary.rst index 87b7014b6fa..ca12067c490 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -76,6 +76,9 @@ Glossary master document The document that contains the root :rst:dir:`toctree` directive. + root document + Same as :term:`master document`. + object The basic building block of Sphinx documentation. Every "object directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst index 798736b0352..6977614cde8 100644 --- a/doc/internals/contributing.rst +++ b/doc/internals/contributing.rst @@ -251,7 +251,7 @@ The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext ``.po`` files translated from the master template :file:`sphinx/locale/sphinx.pot`. -Sphinx uses `Babel `_ to extract messages +Sphinx uses `Babel `_ to extract messages and maintain the catalog files. It is integrated in ``setup.py``: * Use ``python setup.py extract_messages`` to update the ``.pot`` template. @@ -297,7 +297,7 @@ Debugging tips will complain about references without a known target. * Set the debugging options in the `Docutils configuration file - `_. + `_. * JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) are generated by this `modified snowballcode generator diff --git a/doc/latex.rst b/doc/latex.rst index 6e2a34c3b45..f6d2987e206 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -282,7 +282,29 @@ Keys that don't need to be overridden unless in special cases are: "inputenc" package inclusion. Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else - ``''`` + ``''``. + + .. note:: + + If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the + LaTeX preamble with suitable ``\PreloadUnicodePage{}`` commands, + as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based + TeX installation). Else, unexpected and possibly hard-to-spot problems + (i.e. not causing a build crash) may arise in the PDF, in particular + regarding hyperlinks. + + Even if these precautions are taken, PDF build via ``pdflatex`` engine + may crash due to upstream LaTeX not being fully compatible with + ``utf8x``. For example, in certain circumstances related to + code-blocks, or attempting to include images whose filenames contain + Unicode characters. Indeed, starting in 2015, upstream LaTeX with + ``pdflatex`` engine has somewhat enhanced native support for Unicode and + is becoming more and more incompatible with ``utf8x``. In particular, + since the October 2019 LaTeX release, filenames can use Unicode + characters, and even spaces. At Sphinx level this means e.g. that the + :dudir:`image` and :dudir:`figure` directives are now compatible with + such filenames for PDF via LaTeX output. But this is broken if + ``utf8x`` is in use. .. versionchanged:: 1.4.3 Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all @@ -509,6 +531,10 @@ Keys that don't need to be overridden unless in special cases are: Changed default for ``'pdflatex'``. Previously it was using ``'\\fvset{fontsize=\\small}'``. + .. versionchanged:: 4.1.0 + Changed default for Chinese documents to + ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'`` + Keys that are set by other options and therefore should not be overridden are: ``'docclass'`` @@ -686,7 +712,7 @@ Do not use quotes to enclose values, whether numerical or strings. As the default is set to a high value, the forceful algorithm is triggered only in overfull case, i.e. in presence of a string longer than full linewidth. Set this to ``0`` to force all input lines to be hard wrapped - at the current avaiable linewidth:: + at the current available linewidth:: latex_elements = { 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0", @@ -756,7 +782,7 @@ Do not use quotes to enclose values, whether numerical or strings. .. versionchanged:: 1.5 The breaking of long code lines was added at 1.4.2. The default - definition of the continuation symbol was changed at 1.5 to accomodate + definition of the continuation symbol was changed at 1.5 to accommodate various font sizes (e.g. code-blocks can be in footnotes). ``TitleColor`` diff --git a/doc/make.bat b/doc/make.bat index 4bc6ddb9afb..fb183035edd 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -19,7 +19,7 @@ if errorlevel 9009 ( echo.may add the Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ + echo.https://sphinx-doc.org/ exit /b 1 ) diff --git a/doc/templating.rst b/doc/templating.rst index 61b714bfa33..b253723198f 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -6,10 +6,11 @@ Templating ========== -Sphinx uses the `Jinja `_ templating engine for its HTML -templates. Jinja is a text-based engine, inspired by Django templates, so -anyone having used Django will already be familiar with it. It also has -excellent documentation for those who need to make themselves familiar with it. +Sphinx uses the `Jinja `_ templating engine +for its HTML templates. Jinja is a text-based engine, inspired by Django +templates, so anyone having used Django will already be familiar with it. It +also has excellent documentation for those who need to make themselves familiar +with it. Do I need to use Sphinx's templates to produce HTML? @@ -114,7 +115,7 @@ The following blocks exist in the ``layout.html`` template: ``rootrellink``, ``relbaritems`` Inside the relbar there are three sections: The ``rootrellink``, the links from the documentation and the custom ``relbaritems``. The ``rootrellink`` - is a block that by default contains a list item pointing to the master + is a block that by default contains a list item pointing to the root document by default, the ``relbaritems`` is an empty block. If you override them to add extra links into the bar make sure that they are list items and end with the :data:`reldelim1`. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 00000000000..6ff26869516 --- /dev/null +++ b/doc/tutorial/index.rst @@ -0,0 +1,452 @@ +.. _tutorial: + +=============== +Sphinx tutorial +=============== + +In this tutorial you will build a simple documentation project using Sphinx, and +view it in your browser as HTML. The project will include narrative, +handwritten documentation, as well as autogenerated API documentation. + +The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals +of how projects are created and structured. You will create a fictional +software library to generate random food recipes that will serve as a guide +throughout the process, with the objective of properly documenting it. + +To showcase Sphinx capabilities for code documentation you will use Python, +which also supports *automatic* documentation generation. + +.. note:: + + Several other languages are natively supported in Sphinx for *manual* code + documentation, however they require extensions for *automatic* code + documentation, like `Breathe `_. + +To follow the instructions you will need access to a Linux-like command line and +a basic understanding of how it works, as well as a working Python installation +for development, since you will use *Python virtual environments* to create the +project. + +Getting started +--------------- + +Setting up your project and development environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a new directory, create a file called ``README.rst`` with the following +content. + +.. code-block:: rst + :caption: README.rst + + Lumache + ======= + + **Lumache** (/lu'make/) is a Python library for cooks and food lovers that + creates recipes mixing random ingredients. + +It is a good moment to create a Python virtual environment and install the +required tools. For that, open a command line terminal, ``cd`` into the +directory you just created, and run the following commands: + +.. code-block:: console + + $ python -m venv .venv + $ source .venv/bin/activate + (.venv) $ python -m pip install sphinx + +.. note:: + + The installation method used above is described in more detail in + :ref:`install-pypi`. For the rest of this tutorial, the instructions will + assume a Python virtual environment. + +If you executed these instructions correctly, you should have the Sphinx command +line tools available. You can do a basic verification running this command: + +.. code-block:: console + + (.venv) $ sphinx-build --version + sphinx-build 4.0.2 + +If you see a similar output, you are on the right path! + +Creating the documentation layout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Then from the command line, run the following command: + +.. code-block:: console + + (.venv) $ sphinx-quickstart docs + +This will present to you a series of questions required to create the basic +directory and configuration layout for your project inside the ``docs`` folder. +To proceed, answer each question as follows: + +- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without + quotes) and press :kbd:`Enter`. +- ``> Project name``: Write "``Lumache``" (without quotes) and press + :kbd:`Enter`. +- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press + :kbd:`Enter`. +- ``> Project release []``: Write "``0.1``" (without quotes) and press + :kbd:`Enter`. +- ``> Project language [en]``: Leave it empty (the default, English) and press + :kbd:`Enter`. + +After the last question, you will see the new ``docs`` directory with the +following content. + +.. code-block:: text + + docs + ├── build + ├── make.bat + ├── Makefile + └── source + ├── conf.py + ├── index.rst + ├── _static + └── _templates + +The purpose of each of these files is: + +``build/`` + An empty directory (for now) that will hold the rendered documentation. + +``make.bat`` and ``Makefile`` + Convenience scripts to simplify some common Sphinx operations, such as + rendering the content. + +``source/conf.py`` + A Python script holding the configuration of the Sphinx project. It contains + the project name and release you specified to ``sphinx-quickstart``, as well + as some extra configuration keys. + +``source/index.rst`` + The :term:`root document` of the project, which serves as welcome page and + contains the root of the "table of contents tree" (or *toctree*). + +Thanks to this bootstrapping step, you already have everything needed to render +the documentation as HTML for the first time. To do that, run this command: + +.. code-block:: console + + (.venv) $ sphinx-build -b html docs/source/ docs/build/html + +And finally, open ``docs/build/html/index.html`` in your browser. You should see +something like this: + +.. figure:: /_static/tutorial/lumache-first-light.png + :width: 80% + :align: center + :alt: Freshly created documentation of Lumache + + Freshly created documentation of Lumache + +There we go! You created your first HTML documentation using Sphinx. + +First steps to document your project using Sphinx +------------------------------------------------- + +Building your HTML documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``index.rst`` file that ``sphinx-quickstart`` created has some content +already, and it gets rendered as the front page of your HTML documentation. It +is written in reStructuredText, a powerful markup language. + +Modify the file as follows: + +.. code-block:: rst + :caption: docs/source/index.rst + + Welcome to Lumache's documentation! + =================================== + + **Lumache** (/lu'make/) is a Python library for cooks and food lovers that + creates recipes mixing random ingredients. It pulls data from the `Open Food + Facts database `_ and offers a *simple* and + *intuitive* API. + + .. note:: + + This project is under active development. + +This showcases several features of the reStructuredText syntax, including: + +- a **section header** using ``===`` for the underline, +- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically + bold) and ``*emphasis*`` (typically italics), +- an **inline external link**, +- and a ``note`` **admonition** (one of the available :ref:`directives + `) + +Now to render it with the new content, you can use the ``sphinx-build`` command +as before, or leverage the convenience script as follows: + +.. code-block:: console + + (.venv) $ cd docs + (.venv) $ make html + +After running this command, you will see that ``index.html`` reflects the new +changes! + +Building your documentation in other formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, +:ref:`and more `. For example, to build your documentation +in EPUB format, run this command from the ``docs`` directory: + +.. code-block:: console + + (.venv) $ make epub + +After that, you will see the files corresponding to the e-book under +``docs/build/epub/``. You can either open ``Lumache.epub`` with an +EPUB-compatible e-book viewer, like `Calibre `_, +or preview ``index.xhtml`` on a web browser. + +.. note:: + + To quickly display a complete list of possible output formats, plus some + extra useful commands, you can run :code:`make help`. + +Each output format has some specific configuration options that you can tune, +:ref:`including EPUB `. For instance, the default value of +:confval:`epub_show_urls` is ``inline``, which means that, by default, URLs are +shown right after the corresponding link, in parentheses. You can change that +behavior by adding the following code at the end of your ``conf.py``: + +.. code-block:: python + + # EPUB options + epub_show_urls = 'footnote' + +With this configuration value, and after running ``make epub`` again, you will +notice that URLs appear now as footnotes, which avoids cluttering the text. +Sweet! + +.. note:: + + Generating a PDF using Sphinx can be done running ``make latexpdf``, + provided that the system has a working :math:`\LaTeX` installation, + as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`. + Although this is perfectly feasible, such installations are often big, + and in general LaTeX requires careful configuration in some cases, + so PDF generation is out of scope for this tutorial. + +More Sphinx customization +------------------------- + +There are two main ways to customize your documentation beyond what is possible +with core Sphinx: extensions and themes. + +Enabling a built-in extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to these configuration values, you can customize Sphinx even more +by using :doc:`extensions `. Sphinx ships several +:ref:`builtin ones `, and there are many more +:ref:`maintained by the community `. + +For example, to enable the :mod:`sphinx.ext.duration` extension, +locate the ``extensions`` list in your ``conf.py`` and add one element as +follows: + +.. code-block:: python + :caption: docs/source/conf.py + + # Add any Sphinx extension module names here, as strings. They can be + # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom + # ones. + extensions = [ + 'sphinx.ext.duration', + ] + +After that, every time you generate your documentation, you will see a short +durations report at the end of the console output, like this one: + +.. code-block:: console + + (.venv) $ make html + ... + The HTML pages are in build/html. + + ====================== slowest reading durations ======================= + 0.042 temp/source/index + +Using a third-party HTML theme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Themes, on the other hand, are a way to customize the appearance of your +documentation. Sphinx has several :ref:`builtin themes `, and +there are also `third-party ones `_. + +For example, to use the `Furo `_ third-party theme +in your HTML documentation, first you will need to install it with ``pip`` in +your Python virtual environment, like this: + +.. code-block:: console + + (.venv) $ pip install furo + +And then, locate the ``html_theme`` variable on your ``conf.py`` and replace +its value as follows: + +.. code-block:: python + :caption: docs/source/conf.py + + # The theme to use for HTML and HTML Help pages. See the documentation for + # a list of builtin themes. + # + html_theme = 'furo' + +With this change, you will notice that your HTML documentation has now a new +appearance: + +.. figure:: /_static/tutorial/lumache-furo.png + :width: 80% + :align: center + :alt: HTML documentation of Lumache with the Furo theme + + HTML documentation of Lumache with the Furo theme + +Narrative documentation in Sphinx +--------------------------------- + +Structuring your documentation across multiple pages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root +document`, whose main function is to serve as a welcome page and to contain the +root of the "table of contents tree" (or *toctree*). Sphinx allows you to +assemble a project from different files, which is helpful when the project +grows. + +As an example, create a new file ``docs/source/usage.rst`` (next to +``index.rst``) with these contents: + +.. code-block:: rst + :caption: docs/source/usage.rst + + Usage + ===== + + Installation + ------------ + + To use Lumache, first install it using pip: + + .. code-block:: console + + (.venv) $ pip install lumache + +This new file contains two :ref:`section ` headers, normal +paragraph text, and a :rst:dir:`code-block` directive that renders +a block of content as source code, with appropriate syntax highlighting +(in this case, generic ``console`` text). + +The structure of the document is determined by the succession of heading +styles, which means that, by using ``---`` for the "Installation" section +after ``===`` for the "Usage" section, you have declared "Installation" to +be a *subsection* of "Usage". + +To complete the process, add a ``toctree`` :ref:`directive ` at +the end of ``index.rst`` including the document you just created, as follows: + +.. code-block:: rst + :caption: docs/source/index.rst + + Contents + -------- + + .. toctree:: + + usage + +This step inserts that document in the root of the *toctree*, so now it belongs +to the structure of your project, which so far looks like this: + +.. code-block:: text + + index + └── usage + +If you build the HTML documentation running ``make html``, you will see +that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you +to navigate to the new page you just created. Neat! + +.. warning:: + + Documents outside a *toctree* will result in ``WARNING: document isn't + included in any toctree`` messages during the build process, and will be + unreachable for users. + +Adding cross-references +~~~~~~~~~~~~~~~~~~~~~~~ + +One powerful feature of Sphinx is the ability to seamlessly add +:ref:`cross-references ` to specific parts of the documentation: +a document, a section, a figure, a code object, etc. This tutorial is full of +them! + +To add a cross-reference, write this sentence right after the +introduction paragraph in ``index.rst``: + +.. code-block:: rst + :caption: docs/source/index.rst + + Check out the :doc:`usage` section for further information. + +The :rst:role:`doc` role you used automatically references a specific document +in the project, in this case the ``usage.rst`` you created earlier. + +Alternatively, you can also add a cross-reference to an arbitrary part of the +project. For that, you need to use the :rst:role:`ref` role, and add an +explicit *label* that acts as `a target`__. + +__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets + +For example, to reference the "Installation" subsection, add a label right +before the heading, as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + :emphasize-lines: 4 + + Usage + ===== + + .. _installation: + + Installation + ------------ + + ... + +And make the sentence you added in ``index.rst`` look like this: + +.. code-block:: rst + :caption: docs/source/index.rst + + Check out the :doc:`usage` section for further information, including how to + :ref:`install ` the project. + +Notice a trick here: the ``install`` part specifies how the link will look like +(we want it to be a specific word, so the sentence makes sense), whereas the +```` part refers to the actual label we want to add a +cross-reference to. If you do not include an explicit title, hence using +``:ref:`installation```, the section title will be used (in this case, +``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered +as hyperlinks in the HTML documentation. + +Where to go from here +--------------------- + +This tutorial covered the very first steps to create a documentation project +with Sphinx. To continue learning more about Sphinx, check out the :ref:`rest +of the documentation `. diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index 03b77fb6b38..3bf353e8d72 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -13,7 +13,7 @@ navigation bars, Sphinx provides mechanisms facilitating the translation of :width: 100% Workflow visualization of translations in Sphinx. (The figure is created by - `plantuml `_.) + `plantuml `_.) .. contents:: :local: @@ -118,7 +118,7 @@ section describe an easy way to translate with *sphinx-intl*. #. Translate po files. - AS noted above, these are located in the ``./locale//LC_MESSAGES`` + As noted above, these are located in the ``./locale//LC_MESSAGES`` directory. An example of one such file, from Sphinx, ``builders.po``, is given below. @@ -193,7 +193,7 @@ pot file to the po file, use the :command:`sphinx-intl update` command. .. code-block:: console - $ sphinx-intl update -p _build/locale + $ sphinx-intl update -p _build/gettext Using Transifex service for team translation diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst index f4dfb7f669d..7f993e10c54 100644 --- a/doc/usage/advanced/setuptools.rst +++ b/doc/usage/advanced/setuptools.rst @@ -164,7 +164,7 @@ Options for setuptools integration .. setuptools-confval:: link-index - A boolean that ensures index.html will be linked to the master doc. Default + A boolean that ensures index.html will be linked to the root doc. Default is false. This can also be set by passing the `-i` flag to ``setup.py``: diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst index a550803392d..5fa5b00f14c 100644 --- a/doc/usage/advanced/websupport/quickstart.rst +++ b/doc/usage/advanced/websupport/quickstart.rst @@ -61,7 +61,7 @@ This will return a dictionary containing the following items: This dict can then be used as context for templates. The goal is to be easy to integrate with your existing templating system. An example using `Jinja2 -`_ is: +`_ is: .. code-block:: html+jinja @@ -112,8 +112,8 @@ must update the websupport package's data:: should be a boolean representing whether the user has moderation privileges. The default value for *moderator* is ``False``. -An example `Flask `_ function that checks whether a -user is logged in and then retrieves a document is:: +An example `Flask `_ function that checks +whether a user is logged in and then retrieves a document is:: from sphinxcontrib.websupport.errors import * @@ -152,8 +152,8 @@ To use the search form built-in to the Sphinx sidebar, create a function to handle requests to the URL 'search' relative to the documentation root. The user's search query will be in the GET parameters, with the key `q`. Then use the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to -retrieve search results. In `Flask `_ that would be -like this:: +retrieve search results. In `Flask `_ that +would be like this:: @app.route('/search') def search(): diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index 74853fee971..4d5315227d2 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -51,7 +51,7 @@ The builder's "name" must be given to the **-b** command-line option of This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like - the master document. No indices will be generated. + the root document. No indices will be generated. .. autoattribute:: name diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 3c58da30878..18eae9c1902 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -18,8 +18,8 @@ and output behavior. directory to adjust `Docutils`_ configuration if not otherwise overridden or set by Sphinx. - .. _`docutils`: http://docutils.sourceforge.net/ - .. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html + .. _`docutils`: https://docutils.sourceforge.io/ + .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html The configuration file is executed as Python code at build time (using :func:`execfile`, and with the current directory set to its containing @@ -419,6 +419,20 @@ General configuration .. versionadded:: 1.1 +.. confval:: nitpick_ignore_regex + + An extended version of :confval:`nitpick_ignore`, which instead interprets + the ``type`` and ``target`` strings as regular expressions. Note, that the + regular expression must match the whole string (as if the ``^`` and ``$`` + markers were inserted). + + For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings + for all python entities that start with ``'foo'`` and have ``'bar.B'`` in + them, such as ``('py:const', 'foo_package.bar.BAZ_VALUE')`` or + ``('py:class', 'food.bar.Barman')``. + + .. versionadded:: 4.1 + .. confval:: numfig If true, figures, tables and code-blocks are automatically numbered if they @@ -470,7 +484,7 @@ General configuration languages, will be used to convert quotes and dashes to typographically correct entities. Default: ``True``. - __ http://docutils.sourceforge.net/docs/user/smartquotes.html + __ https://docutils.sourceforge.io/docs/user/smartquotes.html __ https://daringfireball.net/projects/smartypants/ .. versionadded:: 1.6.6 @@ -483,8 +497,8 @@ General configuration *deactivates* smart quotes via the corresponding `Docutils option`__. But if it *activates* them, then :confval:`smartquotes` does prevail. - __ http://docutils.sourceforge.net/docs/user/config.html - __ http://docutils.sourceforge.net/docs/user/config.html#smart-quotes + __ https://docutils.sourceforge.io/docs/user/config.html + __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes .. confval:: smartquotes_action @@ -577,17 +591,18 @@ General configuration .. confval:: highlight_language The default language to highlight source code in. The default is - ``'python3'``. The value should be a valid Pygments lexer name, see + ``'default'``. It is similar to ``'python3'``; it is mostly a superset of + ``'python'`` but it fallbacks to ``'none'`` without warning if failed. + ``'python3'`` and other languages will emit warning if failed. + + The value should be a valid Pygments lexer name, see :ref:`code-examples` for more details. .. versionadded:: 0.5 .. versionchanged:: 1.4 - The default is now ``'default'``. It is similar to ``'python3'``; - it is mostly a superset of ``'python'`` but it fallbacks to - ``'none'`` without warning if failed. ``'python3'`` and other - languages will emit warning if failed. If you prefer Python 2 - only highlighting, you can set it back to ``'python'``. + The default is now ``'default'``. If you prefer Python 2 only + highlighting, you can set it back to ``'python'``. .. confval:: highlight_options @@ -780,6 +795,10 @@ documentation on :ref:`intl` for details. The default is ``['locales']``. + .. note:: The :option:`-v option for sphinx-build command ` + is useful to check the locale_dirs config works as expected. It + emits debug messages if message catalog directory not found. + .. versionchanged:: 1.5 Use ``locales`` directory as a default value @@ -1033,7 +1052,7 @@ that use Sphinx's HTMLWriter class. A list of CSS files. The entry must be a *filename* string or a tuple containing the *filename* string and the *attributes* dictionary. The *filename* must be relative to the :confval:`html_static_path`, or a full URI - with scheme like ``http://example.org/style.css``. The *attributes* is used + with scheme like ``https://example.org/style.css``. The *attributes* is used for attributes of ```` tag. It defaults to an empty list. Example:: @@ -1056,7 +1075,7 @@ that use Sphinx's HTMLWriter class. A list of JavaScript *filename*. The entry must be a *filename* string or a tuple containing the *filename* string and the *attributes* dictionary. The *filename* must be relative to the :confval:`html_static_path`, or a full - URI with scheme like ``http://example.org/script.js``. The *attributes* is + URI with scheme like ``https://example.org/script.js``. The *attributes* is used for attributes of ``