Merge pull request #1368 from pradyunsg/page-titles-and-hierarchy

Improve sidebar presentation by tweaking titles and adding "section" pages for `guides/`

Author: pradyunsg

source/guides/index.rst

@@ -6,40 +6,10 @@ already familiar with the basics of Python packaging. If you're looking for an
 introduction to packaging, see :doc:`/tutorials/index`.
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Installing Packages:
-
-   installing-using-pip-and-virtual-environments
-   installing-using-virtualenv
-   installing-stand-alone-command-line-tools
-   installing-using-linux-tools
-   installing-scientific-packages
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Building and Publishing Projects:
-
-   distributing-packages-using-setuptools
-   using-manifest-in
-   single-sourcing-package-version
-   dropping-older-python-versions
-   packaging-binary-extensions
-   packaging-namespace-packages
-   creating-and-discovering-plugins
-   using-testpypi
-   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:
+   :titlesonly:
 
+   section-install
+   section-build-and-publish
+   section-hosting
    tool-recommendations
    analyzing-pypi-package-downloads

source/guides/section-build-and-publish.rst

@@ -0,0 +1,17 @@
+=======================
+Building and Publishing
+=======================
+
+.. toctree::
+   :titlesonly:
+
+   distributing-packages-using-setuptools
+   using-manifest-in
+   single-sourcing-package-version
+   dropping-older-python-versions
+   packaging-binary-extensions
+   packaging-namespace-packages
+   creating-and-discovering-plugins
+   using-testpypi
+   making-a-pypi-friendly-readme
+   publishing-package-distribution-releases-using-github-actions-ci-cd-workflows

source/guides/section-hosting.rst

@@ -0,0 +1,9 @@
+=======
+Hosting
+=======
+
+.. toctree::
+   :titlesonly:
+
+   index-mirrors-and-caches
+   hosting-your-own-index

source/guides/section-install.rst

@@ -0,0 +1,12 @@
+============
+Installation
+============
+
+.. toctree::
+   :titlesonly:
+
+   installing-using-pip-and-virtual-environments
+   installing-using-virtualenv
+   installing-stand-alone-command-line-tools
+   installing-using-linux-tools
+   installing-scientific-packages

source/index.rst

@@ -41,7 +41,7 @@ Overview and Flow
    continuous improvement are key to success. The overview and flow sections
    provide a starting point for understanding the Python packaging ecosystem.
 
-The :doc:`Overview of Python Packaging <overview>` explains Python packaging
+The :doc:`overview` explains Python packaging
 and its use when preparing and distributing projects.
 This section helps you build understanding about selecting the tools and
 processes that are most suitable for your use case.

source/overview.rst

@@ -1,6 +1,6 @@
-===================================
-An Overview of Packaging for Python
-===================================
+============================
+Overview of Python Packaging
+============================
 
 .. Editors, see notes at the bottom of the document for maintenance info.