Taking it to the next level#

Changing the source directory tree#

First of all, its important to note that the files builded using the sphinx-apidoc command serves (for an advance user) as a starting point for building the final documentation, not as the end files of it. So lets modify this files to give the documentation a better look.

First of all I dont like at all the distribution of the files, so we’ll add a directory structure with the main parts of any documentation:

  • User guide: This directory of the documentation will contain files explaining how to use the user intended scripts of the project.

  • API Reference: On the other hand, some users may need an insight on the specific documentation of a object. All the files with the docstrings of your code/source files build up the API Reference part of the documentation.

With this structure on mind, we’ll modify the directories in the source directory to this:

docs dirtree#
build/
source/
├── _apireference/
├── _static/
├── _templates/
└── _userguide/
conf.py
index.py

Where the _userguide directory was created and the _component_autodoc change its name to _apireference (this will be explained on the API Reference section).

Adding the User guide#

First of all, we’ll populate the User guide. On this example we will add 3 files to the _userguide directory:

  1. Introduction file

    This file is the landing page of the user guide and must link to other important files. Also, it states the scope of the guide.

    _userguide/introduction.rst#
     1Component user guide
 2====================
 3
 4This file serves as a landing page for the quickstart guide of your project. It
 5must link to deeper looks into the use of the main files that will be used by
 6the other developers. In this example case, we will link to two other files:
 7
 8
 9.. toctree::
10   :maxdepth: 2
11   :caption: Getting started
12
13   quickstart1
14   quickstart2

  2. Some quickstart file

    This file is only a example of a quickstart tutorial.

    _userguide/quickstart1.rst#
     1Quickstart 1
 2============
 3
 4This file explains how to use some module in a **simplified manner**. Its more 
 5descriptive and must be thinked for anyone to understad what things can be 
 6changed and what difference they will make on the use of the code.
 7
 8Usually, this files explain only the top-level scripts.
 9
10This files are built so the user can simply read it and does not have to see
11the description of every function in your code located on the API Reference.
12
13Some title or section 1
14-----------------------
15
16Wow, think in all the things you can explain here!
17
18
19Some title or section 2
20-----------------------
21
22Wow, think in all the things you can explain here!
23
24
25Some title or section 3
26-----------------------
27
28Wow, think in all the things you can explain here!

  3. Other quickstart file

    This file is only a example of a quickstart tutorial.

    _userguide/quickstart2.rst#
     1Quickstart 2
 2============
 3
 4This file explains how to use some module in a **simplified manner**. Its more 
 5descriptive and must be thinked for anyone to understad what things can be 
 6changed and what difference they will make on the use of the code.
 7
 8Usually, this files explain only the top-level scripts.
 9
10This files are built so the user can simply read it and does not have to see
11the description of every function in your code located on the API Reference.
12
13Some title or section 1
14-----------------------
15
16Wow, think in all the things you can explain here!
17
18
19Some title or section 2
20-----------------------
21
22Wow, think in all the things you can explain here!
23
24
25Some title or section 3
26-----------------------
27
28Wow, think in all the things you can explain here!

Note

Try to add the introduction.rst file to the documentation before proceeding with the guide. If you notice, is the only file needed as it allready have links to the other quickstart files.

Modifiying the API Reference#

If you are familiarized with documentation, you’ve notice that the documentation we build on the Adding Shinx to your project part of this tutorial is the API Reference part of the documentation (hence the change of the directory name). Nevertheless it can be much better than it is. To accomplish this we’ll make use of the Autosummary extension.

With this extension, we’ll generate a documentation that have a page for every file (also known as module) with its file-level docstrings and a summary list of every function, class and exception objects in the module, with links to a separate page (one for every object) with its docstrings.

The templates#

To make your life easier, I build the following two template files that you’ll have to simply put on the _templates directory.

  1. Module template:

    This one handles the automatic documentation of the modules.

    _templates/custom-module-template.rst#
     1{{ name }} {{ objtype[0] | upper }}{{ objtype[1:] }}
 2{{ '=' * ( (name + objtype) | length + 1 ) }}
 3
 4.. automodule:: {{ fullname }}
 5   :no-members:
 6
 7{% block attributes %}
 8{% if attributes %}
 9.. rubric:: Module Attributes
10
11.. autosummary::
12   :toctree:
13{% for item in attributes %}
14   {{ item }}
15{%- endfor %}
16{% endif %}
17{% endblock %}
18
19{% block functions %}
20{% if functions %}
21.. rubric:: {{ _('Functions') }}
22
23.. autosummary::
24   :toctree:
25   :template: custom-object-template.rst
26{% for item in functions %}
27   {{ item }}
28{%- endfor %}
29{% endif %}
30{% endblock %}
31
32{% block classes %}
33{% if classes %}
34.. rubric:: {{ _('Classes') }}
35
36.. autosummary::
37   :toctree:
38   :template: custom-object-template.rst
39{% for item in classes %}
40   {{ item }}
41{%- endfor %}
42{% endif %}
43{% endblock %}
44
45{% block exceptions %}
46{% if exceptions %}
47.. rubric:: {{ _('Exceptions') }}
48
49.. autosummary::
50   :toctree:
51{% for item in exceptions %}
52   {{ item }}
53{%- endfor %}
54{% endif %}
55{% endblock %}
56
57{% block modules %}
58{% if modules %}
59.. rubric:: Modules
60
61.. autosummary::
62   :toctree:
63   :template: custom-module-template.rst
64   :recursive:
65{% for item in modules %}
66   {{ item }}
67{%- endfor %}
68{% endif %}
69{% endblock %}

  2. Object template:

    This other one handles how the classes and functions pages will be documentated:

    _templates/custom-object-template.rst#
     1{{ name }} {{ objtype[0] | upper }}{{ objtype[1:] }}
 2{{ '=' * ( (name + objtype) | length + 1 ) }}
 3
 4.. currentmodule:: {{ module }}
 5
 6{% if objtype == 'function' %}
 7.. autofunction:: {{ objname }}
 8{% endif %}
 9
10{% if objtype == 'class' %}
11.. autoclass:: {{ objname }}
12   :members:
13   :show-inheritance:
14   :inherited-members:
15{% endif %}

If you want to know how this files work, you can read the tangent on deeper look on template files.

Modifiying the ApiDoc files#

So, now that we have the templates, lets modify the files on the now _apireference directory (ex _component_autodoc ). We’ll make the following changes:

  1. Remove the modules.rst and component.rst as we’ll create our own landing page for this section.

  2. Create the landing page file for the API Reference with the following content:

    _apireference/introduction.rst#
     1API Reference
 2=============
 3
 4This is the landing page of the API Reference. You must explain a little the
 5distribution of the packages, subpackages and modules in your project. You
 6cand further divide them into categories or something like that.
 7
 8For example...
 9
10
11Scripts
12-------
13
14On this demo repository there is only one level main script, it will be usefull
15that this file has a quick start guide on the 
16:doc:`User Guide <../_userguide/introduction>`.
17
18.. currentmodule:: component
19
20.. autosummary:: 
21   :template: custom-module-template.rst
22   :toctree: _generated
23
24   file1
25
26
27Packages
28--------
29
30This demo repository only have one package:
31
32.. toctree::
33   :maxdepth: 1
34
35   component.package1

    This file links to the files or packages inside the component project, that is the file1.rst file and the package1 package.

    Note that we have used the autosummary extension with the template that we created to document the code inside the file1.rst file. For this, we’ve explicitly said to Sphinx that we are in the component module (line 18) and that we want that uses the template for modules we’ve built (line 21). The generated files will be saved under the _generated directory inside the current directory (_apireference).

    Note

    Try to add this file to the index.rst to see how the autosummary extension built the documentation for the file1.rst file.

  3. Lets document the other elements of the project using the autosummary extension modifiying the code inside the component.package1.rst, component.package1.subpackage1.rst and component.package1.subpackage2.rst files. Note that no other file will be created by hand because of the use of the extension that will do it for us.

    • The Package 1 file:

      This file represent the package1 directory and all the elements inside it. So it must have two sections, one for the modules (or files) and one for the subpackages.

      _apireference/component.package1.rst#
       1package1 Package
 2==================
 3
 4Some package information.
 5
 6Modules
 7-------
 8
 9.. currentmodule:: component.package1
10
11.. autosummary::
12   :template: custom-module-template.rst
13   :toctree: _generated/package1
14
15   file1
16   file2
17
18Subpackages
19-----------
20
21Some text giving context for the subpackages in the package
22
23.. toctree::
24   :maxdepth: 1
25   :caption: Subpackage index
26
27   component.package1.subpackage1
28   component.package1.subpackage2

      Note that the files are documented analogously to the file1.rst and the subpackages files are linked.

    • The SubPackage 1 file:

      This file represent the subpackage1 directory and all the elements inside it. So it must have only one section for its modules.

      _apireference/component.package1.subpackage1.rst#
       1subpackage1 Subpackage
 2========================
 3
 4Some text giving context for this subpackage
 5
 6Modules
 7-------
 8
 9.. currentmodule:: component.package1.subpackage1
10
11.. autosummary::
12   :template: custom-module-template.rst
13   :toctree: _generated/subpackage1
14
15   subfile1
16   subfile2

    • The SubPackage 2 file:

      This file represent the subpackage2 directory and all the elements inside it. So it must have only one section for its modules.

      _apireference/component.package1.subpackage2.rst#
       1subpackage2 Subpackage
 2========================
 3
 4Some text giving context for this subpackage
 5
 6Modules
 7-------
 8
 9.. currentmodule:: component.package1.subpackage2
10
11.. autosummary::
12   :template: custom-module-template.rst
13   :toctree: _generated/subpackage2
14
15   subfile1
16   subfile2

    Note that this files are also much shorter than the original ones.

Updating and upgrading the index.rst#

The index.rst is the face of your documentation and if you haven’t modified it from the previous section now is broken because we have modified the dirtree

Taking advantage of the fact that we are going to modify it, we can improve it adding a little more text and some cards with buttons linking to the main sections of the documentation:

index.rst#
 1.. demorepo documentation master file, created by
 2   sphinx-quickstart on Wed Nov  8 11:40:43 2023.
 3   You can adapt this file completely to your liking, but it should at least
 4   contain the root `toctree` directive.
 5
 6Welcome to Demorepo's documentation!
 7====================================
 8
 9This is an example text, imagine all the this that you can say on the landing 
10page of your documentation! 
11
12If you look online what are the most common documentation areas, you'll see
13that the most of them have at least an **User guide**, with a guide explaining 
14some features of the project and a **API Reference** with the documentation 
15details for every function, class or object.
16
17In this landing page, we'll add links to this two bigger areas of the
18documentation. Feel free to explore!
19
20.. toctree::
21   :maxdepth: 1
22   :hidden:
23
24   _userguide/introduction
25   _apireference/introduction
26
27
28.. grid::
29
30   .. grid-item-card:: 
31      :text-align: center
32      :shadow: sm
33
34      **User guide**
35      ^^^^^^^^^^^^^^
36
37      The user guide provides in-depth information on the key concepts of the
38      features with useful background information and explanation.
39
40      ++++++++++
41
42      .. button-ref:: _userguide/introduction
43         :color: primary
44         :expand:
45
46         To the User guide
47
48   .. grid-item-card::
49      :text-align: center
50      :shadow: sm
51
52      **API Reference**
53      ^^^^^^^^^^^^^^^^^
54
55      The reference guide contains a detailed description of the functions, 
56      modules, and objects included in this project.
57
58      ++++++++++
59
60      .. button-ref:: _apireference/introduction
61         :color: primary
62         :expand:
63
64         To the API Reference

Note that the TOCTree is hidden so it only serves the purpose of indicate the file hierarchy. The files will be linked using buttons inside cards, which are built on the lines from 28 onwards. Give them a look!