Introduction

Hello everyone! Are you writing Python? I'm currently creating a service using Python + django, but as you're familiar with Pythonista, you know that Python can have a docstring. For example, let's run a simple script like this:

# -*- coding: utf-8 -*-
from __future__ import print_function


def foobar():
    u"This is a meaningless function."
    pass


print(foobar.__doc__)

In Python, you can assign the first string literal that appears in a function, class, or method to __doc__ and later find out what that function means. This is a nice feature, but it's a waste if you can only quote from Python's interactive console screens, IDEs, or various plugins for Python.

So, if you use a document tool called Sphinx that Pythonista often uses, this Docstring will be put together into one. That command is sphinx-apidoc. For details on how to use this, please see the Official Document. Hopefully a Sphinx project will be launched.

Now, in doing test drive, test with watchdog or sniffer Many people will hook up and launch the test every time the file is updated. Therefore, I also use the document as a hook and automatically generate it.

Below is an example of a sniffer.

@runnable
def execute(*args):
    from subprocess import call
    call('cd ../docs;make html', shell=True)
    return call(
        'python manage.py test users --failfast',
        shell=True) == 0

For Linux, sphinx creates a Makefile and builds the documentation from the make command. By creating hooks like this, you'll always have the latest documentation at hand, and you'll be able to check for unintended reSt Syntax mistakes.

Just keep in mind that if you don't include the document directory as a .gitignore file in Git, it can be very annoying.

Of course, some people may be using it in a project in another language because Sphinx's document generation performance is so good, not in a Python project. Also, some people may use it to make materials normally. In such a case, the combination of sniffer + sphinx is very comfortable, so I recommend it. Of course, you can create other file update management tools.

Automatically build Python documentation with Sphinx

Introduction