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

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!

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

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!

pytest 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.

coverage 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

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

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

.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.

Recommended Posts

Two document generation tools that you definitely want to use if you write python
Don't write Python if you want to speed it up with Python
If you want to count words in Python, it's convenient to use Counter.
How to write environment variables that you don't want to put on [GitHub] Python
If you want to make a discord bot with python, let's use a framework
If you want to use Cython, also include python-dev
Solution when you want to use cv_bridge with python3 (virtualenv)
[Python] If you suddenly want to create an inquiry form
If you want your colleagues to use the same language
If you want to use field names with hyphens when updating firestore data in python
I want to use a wildcard that I want to shell with Python remove
I want to know if you install Python on Mac ・ Iroha
[Python] When you want to use all variables in another file
If you want to assign csv export to a variable in python
Indispensable if you use Python! How to use Numpy to speed up operations!
If you write go table driven test in python, it may be better to use subTest
[Python] Use pandas to extract △△ that maximizes ○○
How to write Python document comments (Docstrings)
What to do if you can't use scikit grid search in Python
If you want to include awsebcli with CircleCI, specify the python version
If you want to use NumPy, Pandas, Matplotlib, IPython, SciPy on Windows
I want to use jar from python
[Python] If you want to draw a scatter plot of multiple clusters
If you want to make a Windows application (exe) that can be actually used now using only Python
How to build an environment when you want to use python2.7 after installing Anaconda3
If you want to make a TODO application (distributed) now using only Python
Use PIL in Python to extract only the data you want from Exif
Creating a Python document generation tool because it is difficult to use sphinx
[Python] How to use two types of type ()
I want to use MATLAB feval with python
If you want to create a Word Cloud.
I want to use Temporary Directory with Python2
I want to use ceres solver from python
Useful Python built-in functions that you use occasionally
I want to write to a file with Python
You should know if you use Python! 10 useful libraries
Do you want me to fix that copy?
A convenient function memo to use when you want to enter the debugger if an error occurs when running a Python script.
How to install and use pyenv, what to do if you can't switch python versions
What to do if you don't want to use Japanese column names when using ortoolpy.logistics_network
I want to write in Python! (1) Code format check
I want to write in Python! (2) Let's write a test
[Python] How to write a docstring that conforms to PEP8
I want to write in Python! (3) Utilize the mock
For those who want to write Python with vim
Site notes to help you use NetworkX with Python
The programming language you want to be able to use
I want to use the R dataset in python
I know? Data analysis using Python or things you want to use when you want with numpy
[Python3] Code that can be used when you want to resize images in folder units
[Python] When you want to import and use your own package in the upper directory
If you can't use Beautiful Soup 4 after updating to Python 3.5. ImportError: No module named bs4
[Django] A memorandum when you want to communicate asynchronously [Python3]
I want to initialize if the value is empty (python)
[Introduction to Python] How to write conditional branches using if statements
Use cases that motivate you to use Docker that you have never used
If you write TinderBot in Python, she can do it
[Python] How to write an if statement in one sentence.
Use Azure ML Python SDK 4: Write output to Blob storage-Part 2
Use aggdraw when you want to draw beautifully with pillow
[Road to intermediate Python] Use if statement in list comprehension