Two document generation tools that you definitely want to use if you write python

This is convenient for me, who has been studying python and django in earnest for 3 months! !! !! Here are two document generation tools that I thought I would like to introduce! Outline of each tool → It is described in the order of application method in django.

You can often search for it, but it is listed at the top, but I hope you can refer to it as an application example in django.

Documentation of docstrings using sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documents. Developed by Georg Brandl and published under the BSD license. Originally created for Python documentation, this tool is now used by projects in a wide range of languages to facilitate documentation. (by Official Site)

I found out about Read the docs, a document hosting service for the open source community. By the way, it seems that this service is also made with Django.

-Read the docs Official -Jupyter notebook example

Sphinx requires the use of markup called reStructuredText, but the command sphinx-apidoc can automatically generate the rst source. The original text to convert to rst uses docstring. It seems that sphinx.ext.autodoc described in conf.py of the sphinx configuration file will search for the docstring under the original directory. In other words python docstring -> rst -> html It means that sphinx will do all the conversion for you! Overwhelming thanks! !!

Creation procedure

Let's create a document for the django project right away!

• It is necessary to write docstring in python project in advance. What is the docstring that came out earlier? This article is recommended for those who like it →-Introduction to Google docstring

Execute the following command in the terminal.

#Library and theme installation
pip install sphinx sphinx-rtd-theme
#Document output destination creation
mkdir docs
#Create rst with django project root
sphinx-apidoc -fF -o ./docs ./path/to/django_project_root
# change directory
cd docs
# conf.Adjustment of py(The content is written separately!)
vi conf.py
#html creation
make html

• conf.py

Only the additional part is described. Please refer to # --hogehoge -------- for the additional position.

conf.py

# -- Path setup --------------------------------------------------------------

#Specify the path and settings to the django project
import os
import sys
sys.path.insert(0, os.path.abspath('path/to/django_project_root'))
import django
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
django.setup()

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon', # google,numpy style docstring support
]

language = 'ja' #Ai Amu Japan

# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinx_rtd_theme' #Specify the appearance of Read the Docs

It's just automatically generated, but it's quite complete! This article was helpful for those who want to arrange the automatically output rst → study sphinx I also modified rst partly because the link destination described in rst conflicted with the directory name used in the django project (・ _ ・)

Coverage report using coverage

Next is the generation of coverage reports! Click here for the completed image → [https://nedbatchelder.com/files/sample_coverage_html/index.html) There are two tools to use, pytest and coverage!

Official: pytest

pytest is a mature, full-featured Python testing tool that helps you write better programs. The pytest framework makes it easy to write small tests, but it can be extended to support complex functional tests of applications and libraries. (by official)

It is one of the python test frameworks. There is a python standard unittest test framework, but I personally prefer pytest because the comparison operators are easier to write intuitively.

Official: coverage

Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program, records what part of your code was executed, and analyzes the source to identify code that might have been executed but not. Coverage measurements are typically used to assess the effectiveness of a test. You can show which parts of the code are being run by the test and which are not. (By official)

It helps to check the completeness of the code tested. If you set it to 100%, you will be satisfied, but be careful as there are still more things to check.

One of the functions of coverage is the function of outputting report html.

--Easy to understand the tested part --You can reduce the trouble of creating documents

And two birds with one stone! Please use it!

Creation procedure

Now let's set up pytest and coverage in the Django project and output the report!

Execute the following command in the terminal.

#Install library
pip install pytest-django coverage
# change directory(django project directory)
cd django_project_path
# pytest.ini adjustment(The content is written separately!)
vi pytest.ini
# p.Adjustment of coveragerc(The content is written separately!)
vi .coveragerc
#Get coverage
coverage run -m pytest
#Check coverage report
coverage report -m
#coverage html output
coverage html

• pytest.ini

This time I set it to the minimum setting. The official pytest-django is also small and easy to understand, so check it out.

pytest.ini

[pytest]
addopts = --ds=config.settings #Specify django settings
python_files = tests.py test_*.py #Specify test code

• .coveragerc

A file that defines run, report, and html options for the coverage command. The option explanation of the official coverage is also easy to understand with a small amount. In addition to html output, xml and json output are also possible.

.coveragerc

[run]
source=. #Specify django project root
omit= */migrations/*　#Describe the files and directories you want to exclude
      */tests/*
      */htmlcov/*
[report]
omit= */migrations/*
      */tests/*
[html]
directory = htmlcov #Output html to a directory called htmlcov

• If you want to get html coverage, execute pip install django-coverage-plugin and add the following.

.coveragerc

[run]
plugins =
    django_coverage_plugin

Reference: Django memo (26): Measure coverage with coverage.py

This is also an easy operation, and easy-to-read documents can be automatically generated! When using a command, it is easy to check the line numbers that are not covered by coverage report -m, or display the test details with pytest -v.

Finally

You can create a document with less effort, so if you are allowed to use it, your work efficiency will improve. This time I took django as an example, but you can use it even if you are not django, so please try it. If you have any other recommended automatic document creation tools, I would appreciate it if you could comment.

Thank you for reading.