4 - Documentation

Documentation is anything that can be written in addition to some code to help someone understand how it works.
When implementing a library like ManimGraphLibrary, writing a proper documentation is crucial also to allow potential users to understand why the library might be useful for them.
In Section Manim Community Standards we go through the documentation standards set by the Manim Community, in which is stressed the importance of adding clear descriptions and examples to classes and functions. Since we decided to apply those standards to this project, we look into the details about how to document code following them.
In addition, in Section Generating documentation with Sphinx we describe the process we followed to export the documentation of ManimGraphLibrary. We used a documentation generator called Sphinx, a tool that allowed us to easily create a dynamic web page with the documentation of the whole library.

Manim Community standards

As anticipated, the code of this project has been documented following the standards set by the Manim Community [11]. The documentation of Manim is written using docstrings, which are string literals supported by multiple programming languages, including Python, and are used right after the definition of a module, function, class, or method. Unlike comments, docstrings are kept throughout the runtime of the program and this comes useful when generating documentation automatically, as we will see in Section Generating documentation with Sphinx [5].
The documentation of Manim uses the numpy format for sections and formatting, making it possible to render it using Sphinx, a documentation generator written and used by the Python community, but providing at the same time docstrings that are easy to read on text-only terminals [21].
The docstring consists of a number of sections separated by headings, each one underlined in hyphens. Let us go through each section while looking at the documentation of the function node_layout() as an example.
Right after the definition of the function, we find the description of what the function does. The description can be long or short, depending on what is more appropriate, and should start in the same line as the three quotes. This section (Code 4.1) should be used to clarify the functionalities of the function, not to discuss implementation details or background theory, which should rather be explored in the Notes section (Code 4.4).

In the Parameters section (Code 4.2) we list all the parameters and specify how each one works or what it represents. There is no need to specify here the default values of the parameters, as these are already present in the function’s signature (e.g. 'kamada_kawai_layout' is the default value for the parameter layout).

Next we have the Returns section (Code 4.3), which can be omitted if return is never specified (hence the function returns None) and it is clear why the function does not return anything. Otherwise the section should be present and should contain the return value's type and and a description of what the function returns. The name of each return value is optional.

Adding a Notes section is optional. This section (Code 4.4) can be useful to include additional information about the code, possibly providing a discussion of the algorithm. This section may also feature LaTeX-formatted mathematical equations.

It is possible to add also an Examples section (Code 4.5). Adding simple examples to the documentation is highly recommended, since they are a great resource for quickly understanding how a function works.
We use the directive (a generic block of explicit markup) .. manim:: to allow each example to be identified as a scene that will be run by the current version of Manim when rendering the HTML documentation.
In addition, the name of the class representing the scene to be rendered (NodeLayout in Code 4.5) must be passed to the directive.
The directive supports different configuration options, such as hide_source, which specify whether the source code is displayed above the rendered video, and quality, which controls render quality of the video. More options are available in the documentation [16].

Generating documentation with Sphinx

Sphinx is a documentation generator that can be used to obtain different output formats starting from a set of plain text source files. For this specific project, we are interested in generating an HTML file.
Once the documentation has been written following the structure presented in Section Manim Community Standards, we are ready to run the commands that build the web page we are interested in.
Sphinx comes with a script called sphinx-quickstart that sets up a source directory in which we find a conf.py file with the main configuration parameters. Sphinx gets these parameters by presenting a series of questions that the tool requires to create the desired directory and configuration layout.
We are interested in adding the extension sphinx.ext.autodoc to conf.py, which imports the modules of the project and pulls in documentation from docstrings in a semi-automatic way [26].
We also add the extension sphinx.ext.napoleon, which processes numpy docstrings (the ones described in Section Manim Community Standards) and converts them to reStructuredText, the default plaintext markup language used by Sphinx [25].
Optionally we can specify the desired theme for the web page. For this project we chose a theme called furo.
At this point we run the command sphinx-apidoc followed by the path of the target modules, that generates source files that use sphinx.ext.autodoc to document all found modules. Adding the -o option allows us to specify also a directory where to place the output files.
Now everything is set and we can render the documentation as HTML by running sphinx-build -b html followed by the source and the target folder.
When the docstring gets edited we can update the HTML file just by running again this last command.
Let us go back to the function node_layout() used as the example in Section Manim Community Standards. In section node_layout() it is possible to see the output generated through this process.