QueryJane | Python code Autodoc configuration - Documented Account module.

Repository
https://github.com/roadhousestudio/queryjane_app

QueryJane is a web application developed with Django that allows to connect with companies and experts in different sectors of the cannabis industry. Beta version is available here.

Details

I have been working to activate the Sphinx autodoc module. This allows to include in our project documentation the docstrings include in our python code. In this way, we can add documentation to our Python modules and pull it in our final official documentation in a semi-automatic way.

Take a look to the correct way to add docstring to our Python code:

In this way, Sphinx will recognize the added docstrings and will include them in the generated documentation.

I will show you how to indicate to Sphinx that a documented file must be included. Per example, if we want to include to docstrings from the account.models.py file, we must add the following code into the .rst files:

In this way, we are telling to Sphinx that must include all the members of the account/models.py module into the final documentation. Also, we are including all the inherited members and we are including the inheritance path. To goal of include the inheritance documentation, is that in most cases the classes and functions that we are generation have some type of inheritance, and many times we want to override these inherited members. Include this in the documentation allow us to find the members structure in a easy way, without having to go look in the Django repository.

In this documentation update, I have documented the account app Python files. This is the detailed structure of the new documentation module, in which I'm adding all Python files of this module.

To include docstrings from Python files, we must add some lines to the conf.py file. really, and because I'm new using Sphinx, find the correct lines to include the docstring from the Python files in the correct way took me a long time. These are the necessary Sphinx configuration to include docstrings from Python files in a Django project.

import os
import sys
sys.path.insert(0, os.path.abspath('../../')) # Path the the project root from the current file location

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app.settings')

# Setup Django
import django
django.setup()

It takes a lot of time to me and, after a lot of failed attempts, I have created this question in Stackoverflow. Somebody give me the solution and for this reason I was able to create the new documentation module.

Components

The new documented parts are all the classes and functions defined in the Python files in the account app.

Difference

The impact is that now the defined classes and functions can be easily found, including their inherited members. Per now, I'm including only the Python files of one specific module, but the necessary settings to run Sphinx autodoc in the project in a correct way has been configured and it will allows to document the other modules very fast.

Links

New documentation module is available in the following url:

http://docs.queryjane.net/code_documentation.html

Documentation homepage:

http://docs.queryjane.net/

GitHub Proof of Authorship

• https://github.com/aaquirogal

This update includes PRs From 103 to 114, but many of these PRs are about some fixes, typo bugs and changes to testing the correct configuration. The following list shows the most relevant PRs.

103
104
109
113