Merge branch 'main' into add-glossary-build-backend-frontend

webknjaz · web-flow · commit 1cc4e2c40277 · 2023-11-06T02:54:32.000+01:00
diff --git a/requirements.txt b/requirements.txt
@@ -1,7 +1,7 @@
-sphinx==4.5.0
+sphinx==7.2.6
 sphinx-autobuild==2021.3.14
-sphinx-inline-tabs==2021.4.11b9
+sphinx-inline-tabs==2023.4.21
 python-docs-theme==2023.9
-sphinx-copybutton==0.5.0
+sphinx-copybutton==0.5.2
 pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
 sphinx-toolbox==3.5.0
diff --git a/source/conf.py b/source/conf.py
@@ -88,7 +88,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 locale_dirs = ['../locales']
 
@@ -379,11 +379,11 @@
 
 # -- Options for extlinks extension ---------------------------------------
 extlinks = {
-    'issue': (f'{github_repo_issues_url}/%s', '#'),  # noqa: WPS323
-    'pr': (f'{github_repo_url}/pull/%s', 'PR #'),  # noqa: WPS323
-    'commit': (f'{github_repo_url}/commit/%s', ''),  # noqa: WPS323
-    'gh': (f'{github_url}/%s', 'GitHub: '),  # noqa: WPS323
-    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
+    'issue': (f'{github_repo_issues_url}/%s', '#%s'),  # noqa: WPS323
+    'pr': (f'{github_repo_url}/pull/%s', 'PR #%s'),  # noqa: WPS323
+    'commit': (f'{github_repo_url}/commit/%s', '%s'),  # noqa: WPS323
+    'gh': (f'{github_url}/%s', 'GitHub: %s'),  # noqa: WPS323
+    'user': (f'{github_sponsors_url}/%s', '@%s'),  # noqa: WPS323
 }
 
 linkcheck_ignore = [
diff --git a/source/contribute.rst b/source/contribute.rst
@@ -32,9 +32,12 @@ Documentation types
 ===================
 
 This project consists of four distinct documentation types with specific
-purposes. When proposing new additions to the project please pick the
+purposes. The project aspires to follow the `Diátaxis process`_
+for creating quality documentation. When proposing new additions to the project please pick the
 appropriate documentation type.
 
+.. _Diátaxis process: https://diataxis.fr/
+
 Tutorials
 ---------
 
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -15,7 +15,7 @@ development as a whole.  For example, it does not provide guidance or tool
 recommendations for version control, documentation, or testing.
 
 For more reference material, see :std:doc:`Building and Distributing
-Packages <userguide/index>` in the :ref:`setuptools` docs, but note
+Packages <setuptools:userguide/index>` in the :ref:`setuptools` docs, but note
 that some advisory content there may be outdated. In the event of
 conflicts, prefer the advice in the Python Packaging User Guide.
 
@@ -717,7 +717,7 @@ Lastly, if you don't want to install any dependencies at all, you can run:
 
 For more information, see the
 :doc:`Development Mode <setuptools:userguide/development_mode>` section
-of the :doc:`setuptools docs <setuptools>`.
+of the :ref:`setuptools` docs.
 
 .. _`Packaging your project`:
 
diff --git a/source/guides/index.rst b/source/guides/index.rst
@@ -13,8 +13,6 @@ introduction to packaging, see :doc:`/tutorials/index`.
    installing-stand-alone-command-line-tools
    installing-using-linux-tools
    installing-scientific-packages
-   index-mirrors-and-caches
-   hosting-your-own-index
 
 .. toctree::
    :maxdepth: 1
@@ -31,6 +29,13 @@ introduction to packaging, see :doc:`/tutorials/index`.
    making-a-pypi-friendly-readme
    publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Hosting
+
+   index-mirrors-and-caches
+   hosting-your-own-index
+
 .. toctree::
    :maxdepth: 1
    :caption: Miscellaneous:
diff --git a/source/overview.rst b/source/overview.rst
@@ -167,7 +167,7 @@ Python's native packaging is mostly built for distributing reusable
 code, called libraries, between developers. You can piggyback
 **tools**, or basic applications for developers, on top of Python's
 library packaging, using technologies like
-:doc:`setuptools entry_points <userguide/entry_point>`.
+:doc:`setuptools entry_points <setuptools:userguide/entry_point>`.
 
 Libraries are building blocks, not complete applications. For
 distributing applications, there's a whole new world of technologies
diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
@@ -36,7 +36,7 @@ This means that the following names are all equivalent:
 * ``friendly.bard``
 * ``friendly_bard``
 * ``friendly--bard``
-* ``FrIeNdLy-._.-bArD`` (a _terrible_ way to write a name, but it is valid)
+* ``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)
 
 History
 =======
diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst
@@ -1,66 +1,7 @@
-.. _creating-documentation:
+:orphan:
 
+Creating documentation
 ======================
-Creating Documentation
-======================
-
-This section covers the basics of how to create documentation using `Sphinx`_ and
-host the documentation for free in `Read The Docs`_.
-
-.. _Sphinx: https://www.sphinx-doc.org
-.. _Read The Docs: https://readthedocs.org/
-
-Installing Sphinx
------------------
-Use ``pip`` to install Sphinx:
-
-.. tab:: Unix/macOS
-
-    .. code-block:: bash
-
-        python3 -m pip install --upgrade sphinx
-
-.. tab:: Windows
-
-    .. code-block:: bat
-
-        py -m pip install --upgrade sphinx
-
-For other installation methods, see this :doc:`installation guide <sphinx:usage/installation>` by Sphinx.
-
-
-Getting Started With Sphinx
----------------------------
-
-Create a ``docs`` directory inside your project to hold your documentation:
-
-.. code-block:: bash
-
-	cd /path/to/project
-	mkdir docs
-
-Run ``sphinx-quickstart`` inside the ``docs`` directory:
-
-.. code-block:: bash
-
-	cd docs
-	sphinx-quickstart
-
-This sets up a source directory, walks you through some basic configurations, and creates an ``index.rst`` file as well as a ``conf.py`` file.
-
-You can add some information about your project in ``index.rst``, then build them:
-
-.. code-block:: bash
-
-	make html
-
-For more details on the build process, see this `guide`_ by Read The Docs.
-
-.. _guide: https://docs.readthedocs.io/en/latest/intro/import-guide.html
-
-Other Sources
--------------
-
-For a more detailed guide on how to use Sphinx and reStructuredText, please see this `documentation tutorial`_ on Hitchhiker's Guide to Python.
 
-.. _documentation tutorial: https://docs.python-guide.org/writing/documentation/
+This tutorial has been removed since it is not related to packaging and was unmaintained.
+Please see the `Sphinx tutorial <https://www.sphinx-doc.org/en/master/tutorial>`_ instead.
diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst
@@ -11,4 +11,3 @@ topics, see :doc:`/guides/index`.
     installing-packages
     managing-dependencies
     packaging-projects
-    creating-documentation
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
@@ -277,7 +277,7 @@ that the virtual environment's variables are set within the current
 shell, and not in a subprocess (which then disappears, having no
 useful effect).
 
-In both of the above cases, Windows users should _not_ use the
+In both of the above cases, Windows users should *not* use the
 :command:`source` command, but should rather run the :command:`activate`
 script directly from the command shell like so:
 
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
@@ -54,8 +54,8 @@ Create the following file structure locally:
 The directory containing the Python files should match the project name. This
 simplifies the configuration and is more obvious to users who install the package.
 
-:file:`__init__.py` is required to import the directory as a package, and
-should be empty.
+:file:`__init__.py` is required to import the directory as a package,
+even if as is our case for this tutorial that file is empty.
 
 :file:`example.py` is an example of a module within the package that could
 contain the logic (functions, classes, constants, etc.) of your package.
