📝 Rearrange documentation section

Author: veit

CHANGELOG.rst

@@ -13,6 +13,14 @@ emergencies when we need to start branches for older versions.
 
 .. _changelog:
 
+`Unreleased <https://github.com/veit/python-basics-tutorial/compare/24.3.0...HEAD>`_
+------------------------------------------------------------------------------------
+
+Changed
+~~~~~~~
+
+* 📝 Rearrange documentation section
+
 `24.3.0 <https://github.com/veit/python-basics-tutorial/compare/24.2.0...24.3.0>`_: 2024-10-27
 ----------------------------------------------------------------------------------------------
 

docs/document/badges.rst

@@ -0,0 +1,35 @@
+Badges
+======
+
+Some of this information and more can be accessed as badges. They are helpful in
+getting a quick overview of a product. For the
+`cookiecutter-namespace-template
+<https://github.com/veit/cookiecutter-namespace-template>`_ these are, for
+example:
+
+|Downloads| |Versions| |Contributors| |License| |Docs|
+
+.. |Downloads| image::
+   https://static.pepy.tech/badge/cookiecutter-namespace-template
+   :target: https://www.pepy.tech/projects/cookiecutter-namespace-template
+.. |Versions| image::
+   https://img.shields.io/pypi/pyversions/cookiecutter-namespace-template.svg
+   :target: https://pypi.org/project/cookiecutter-namespace-template/
+.. |Contributors| image::
+   https://img.shields.io/github/contributors/veit/cookiecutter-namespace-template.svg
+   :target: https://github.com/veit/cookiecutter-namespace-template/graphs/contributors
+.. |License| image::
+   https://img.shields.io/github/license/veit/cookiecutter-namespace-template.svg
+   :target: https://github.com/veit/cookiecutter-namespace-template/blob/main/LICENSE
+.. |Docs| image::
+   https://readthedocs.org/projects/cookiecutter-namespace-template/badge/?version=latest
+   :target: https://cookiecutter-namespace-template.readthedocs.io/en/latest/
+
+You can also create your own badges, for example:
+
+ .. image:: https://img.shields.io/badge/dynamic/json?label=Mastodon&query=totalItems&url=https%3A%2F%2Fmastodon.social%2F@JupyterTutorial%2Ffollowers.json&logo=mastodon
+    :alt: Mastodon
+    :target: https://mastodon.social/@JupyterTutorial
+
+.. seealso::
+    * `shields.io <https://shields.io>`_

docs/document/index.rst

@@ -46,102 +46,6 @@ or ``LICENSES`` folder) and how to get help if needed.
    :titlesonly:
    :hidden:
 
-   start
-   rest
-   code-blocks
-   placeholder
-   ui-elements
-   directives
-   docstrings
-   intersphinx
-   uml/index
-   extensions
-   test
+   sphinx/index
+   badges
    shot-scraper
-
-Badges
-------
-
-Some of this information and more can be accessed as badges. They are helpful in
-getting a quick overview of a product. For the
-`cookiecutter-namespace-template
-<https://github.com/veit/cookiecutter-namespace-template>`_ these are, for
-example:
-
-|Downloads| |Versions| |Contributors| |License| |Docs|
-
-.. |Downloads| image::
-   https://static.pepy.tech/badge/cookiecutter-namespace-template
-   :target: https://www.pepy.tech/projects/cookiecutter-namespace-template
-.. |Versions| image::
-   https://img.shields.io/pypi/pyversions/cookiecutter-namespace-template.svg
-   :target: https://pypi.org/project/cookiecutter-namespace-template/
-.. |Contributors| image::
-   https://img.shields.io/github/contributors/veit/cookiecutter-namespace-template.svg
-   :target: https://github.com/veit/cookiecutter-namespace-template/graphs/contributors
-.. |License| image::
-   https://img.shields.io/github/license/veit/cookiecutter-namespace-template.svg
-   :target: https://github.com/veit/cookiecutter-namespace-template/blob/main/LICENSE
-.. |Docs| image::
-   https://readthedocs.org/projects/cookiecutter-namespace-template/badge/?version=latest
-   :target: https://cookiecutter-namespace-template.readthedocs.io/en/latest/
-
-You can also create your own badges, for example:
-
- .. image:: https://img.shields.io/badge/dynamic/json?label=Mastodon&query=totalItems&url=https%3A%2F%2Fmastodon.social%2F@JupyterTutorial%2Ffollowers.json&logo=mastodon
-    :alt: Mastodon
-    :target: https://mastodon.social/@JupyterTutorial
-
-.. seealso::
-    * `shields.io <https://shields.io>`_
-
-Sphinx
-------
-
-For extensive documentation you can, for example, use `Sphinx
-<https://www.sphinx-doc.org/>`_, a documentation tool that converts
-reStructuredText into HTML or PDF, EPub and man pages. The Python Basics are
-also created with Sphinx. To get a first impression of Sphinx, you can have a
-look at the source code of this page by following the link `Sources
-<../_sources/document/index.rst.txt>`_.
-
-Originally, Sphinx was developed for the documentation of Python and is now
-used in almost all Python projects, including `NumPy and SciPy
-<https://docs.scipy.org/doc/>`_, `Matplotlib
-<https://matplotlib.org/stable/users/index.html>`_, `Pandas
-<https://pandas.pydata.org/docs/>`_ and `SQLAlchemy
-<https://docs.sqlalchemy.org/>`_.
-
-The Sphinx `autodoc
-<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ feature,
-which can be used to create documentation from Python
-:doc:`docstrings`, may also be conducive to the spread of Sphinx among Python
-developers. Overall, Sphinx allows developers to create complete documentation
-in place. Often the documentation is also stored in the same :doc:`Git
-<Python4DataScience:productive/git/index>` repository, so that the creation of
-the latest software documentation remains easy.
-
-Sphinx is also used in projects outside the Python community, e.g. for the
-documentation of the Linux kernel: `Kernel documentation update
-<https://lwn.net/Articles/705224/>`_.
-
-`Read the Docs <https://about.readthedocs.com/>`_ was developed to forther
-simplify documentation. Read the Docs makes it easy to create and publish
-documentation after each commit.
-
-For project documentation, visualising :doc:`Git feature branches
-<Python4DataScience:productive/git/workflows/feature-branches>` and :doc:`tags
-<Python4DataScience:productive/git/tag>` with
-:doc:`Python4DataScience:productive/git/advanced/git-big-picture` can be
-helpful.
-
-.. note::
-   If the content of ``long_description`` in ``setup()`` is written in
-   reStructured Text, it is displayed as well-formatted HTML on the
-   :term:`Python Package Index` (:term:`PyPI`).
-
-Other documentation tools
--------------------------
-
-`Pycco <https://pycco-docs.github.io/pycco/>`_
-    is a Python port of `Docco <https://github.com/jashkenas/docco>`_.

docs/document/autodoc-examples.rst docs/document/sphinx/autodoc-examples.rstdocs/document/autodoc-examples.rst renamed to docs/document/sphinx/autodoc-examples.rst

@@ -0,0 +1,60 @@
+Sphinx
+======
+
+For extensive documentation you can, for example, use `Sphinx
+<https://www.sphinx-doc.org/>`_, a documentation tool that converts
+reStructuredText into HTML or PDF, EPub and man pages. The Python Basics are
+also created with Sphinx. To get a first impression of Sphinx, you can have a
+look at the source code of this page by following the link `Sources
+<../_sources/document/index.rst.txt>`_.
+
+Originally, Sphinx was developed for the documentation of Python and is now
+used in almost all Python projects, including `NumPy and SciPy
+<https://docs.scipy.org/doc/>`_, `Matplotlib
+<https://matplotlib.org/stable/users/index.html>`_, `Pandas
+<https://pandas.pydata.org/docs/>`_ and `SQLAlchemy
+<https://docs.sqlalchemy.org/>`_.
+
+The Sphinx `autodoc
+<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ feature,
+which can be used to create documentation from Python
+:doc:`docstrings`, may also be conducive to the spread of Sphinx among Python
+developers. Overall, Sphinx allows developers to create complete documentation
+in place. Often the documentation is also stored in the same :doc:`Git
+<Python4DataScience:productive/git/index>` repository, so that the creation of
+the latest software documentation remains easy.
+
+Sphinx is also used in projects outside the Python community, e.g. for the
+documentation of the Linux kernel: `Kernel documentation update
+<https://lwn.net/Articles/705224/>`_.
+
+`Read the Docs <https://about.readthedocs.com/>`_ was developed to forther
+simplify documentation. Read the Docs makes it easy to create and publish
+documentation after each commit.
+
+For project documentation, visualising :doc:`Git feature branches
+<Python4DataScience:productive/git/workflows/feature-branches>` and :doc:`tags
+<Python4DataScience:productive/git/tag>` with
+:doc:`Python4DataScience:productive/git/advanced/git-big-picture` can be
+helpful.
+
+.. note::
+   If the content of ``long_description`` in ``setup()`` is written in
+   reStructured Text, it is displayed as well-formatted HTML on the
+   :term:`Python Package Index` (:term:`PyPI`).
+
+.. toctree::
+    :titlesonly:
+    :hidden:
+
+    start
+    rest
+    code-blocks
+    placeholder
+    ui-elements
+    directives
+    docstrings
+    intersphinx
+    uml/index
+    extensions
+    test