This article is from the Maya-Python Advent Calendar December 11th.

Introduction

One of the features of Python is documentation strings.

It is interpreted as a document by writing the following character strings in modules, classes, functions, etc.

`python`


def sayhello():
    u"""Hello and cheerfully say hello."""
    sys.stdout.write(u"Hello!")

If you pass it to the help method, it will be formatted and output, so use it to find out how to use the function.

>>> help(sayhello)
Help on function sayhello in module __main__:

sayhello()
Hello and cheerfully say hello

Of course, standard modules are also described.

>>> import os
>>> help(os.path.abspath)
Help on function abspath in module ntpath:

abspath(path)
    Return the absolute version of a path.

Verification environment

Windows10 Python 2.7.12 PyCharm 2016.3 Sphinx 1.5 Maya 2016 Extension2

Problems we have

We manage a large number of modules, methods and classes as shared libraries. Even at this point, the number of functions is too large to remember everything. Of these, the maya package only works with maya built-in Python. There are other built-in Python-dependent packages, but this time I'll limit myself to maya.

stu/
  __init__.py
  maya/
    __init__.py
    skin.py
Many others ...
  path.py
  pyside.py
Many others ...

Promote the use of shared libraries
Avoid reinventing the wheel

For the above two reasons, there is a need for a system that can be easily searched with the desired function and has high visibility in the method argument specifications.

Since I have also created test code, I can understand how to use it by looking at the test code, but of course I do not know how the current specifications are made, and the test code is not good in the first place. Often enough.

So, the story is "let's leave a note on the docstring properly", but I myself am not writing it very aggressively.

Humans need motivation to act.

So how do you motivate yourself? So I would like to reconsider the docstring.

Problems not maintained

As mentioned in PEP8, the worst thing is that the code and comments don't match. I don't know which one is correct. It would be better not to write comments that are not maintained.

Why don't you just write excuses like that? Isn't it simply because there is no benefit to me?

Python is evolving day by day. Starting with Python 3.5, a function to define the type of a variable called Type Hints (PEP484) has been added. It is possible to define the types of arguments and return values, and if the editor supports it, the methods of the returned variables can be displayed as candidates. In PyCharm, Type Hinting As a function, Type Hints of Python3.5 and how to describe in docstrings Seems to support it.

This seems to be an incentive to maintain the docstring.

Now, I would like to do the following verification and get the HTML document while using docstring conveniently.

PyCharm Type Hinting
Search documents in HTML with Sphinx

Verify Type Hinting

It seems that Type Hints was introduced in Python 3.5, so it seems that there is a way to express it in some comments, but it can not be used in Python 2, so I decided to reject it.

First, as usual, make sure Project Interpreter is mayapy. If this is neglected, even if you define the type of pymel etc., it will not work.

Let's define the return value of the function. Try specifying SkinCluster with `` `rtype```. So, try calling a function and storing it in a variable.

If you type a method from that variable ... the skinCluster object's method will be a candidate. Of course, the methods of the parent class. Great···

Now there is no reason not to write rtype easily.

Validate Sphinx

Python has several mechanisms to automatically generate HTML documents from source code, but recently it has also been focusing on supporting programming languages other than Python Sphinx. /en/1.5/) is probably the most common. The official documentation for Python itself is also Sphinx. Rather, it seems that it was developed for that purpose.

Automatically generate a document with Sphinx so that you can search for the information written in the docstring.

For the time being, install sphinx with pip.

"C:\Program Files\Autodesk\Maya2016\bin\mayapy.exe" -m pip install sphinx --user

Since Sphinx is also available in PyCharm, specify the document directory. This time it is C: \ sample \ sphinx.

Run Sphinx Quickstart to create a configuration file interactively. Basically, the language is set to ja, and the rest is OK by default. (Sorry for the rough explanation)

With this alone, docstrings are irrelevant and only create html from a text file (.rst) in reStructuredText format, so [sphinx-apidoc](http://www.sphinx-doc.org/ja/stable/invocation.html# Invocation-of-sphinx-apidoc) is used separately to generate a .rst file that generates API documentation from the source code. It will be executed on the command line.

%USERPROFILE%\AppData\Roaming\Python\Scripts\sphinx-apidoc.exe library path-o C:\sample\sphinx

Now you are ready. Next is the execution of document generation. Go back to PyCharm and create a new Config from Run / Debug Configurations. Python docs / Sphinx task is prepared properly ... Specify input and output and it's done. I think the Interpreter is mayapy, but please note that Sphinx imports the module to document and gets the docstrings, so in normal Python an import error will occur and the documentation will also fail.

So, Run as usual. C: \ sample \ sphinx \ _ build \ index.html (and many others) should be generated.

Open index.html. In the default state, html is generated, but let's search for it.

Oh, the result came out. (One is garbage)

Oh! The type of the return value described in the docstring is described properly.

Summary

A lot of know-how for docstrings came from the web. There seem to be some candidates for the markup format, but for the time being, I will write it in reStructuredText, which is the standard Python markup. As with this sentence written in Qiita, is markdown the de facto standard for markup languages in the world? I'm a little worried because it's not surprising, but I don't need to rush to the conclusion because the purpose is not a document with such a complicated structure in the first place. I will think about it at another time.

Sphinx feels a bit tricky to run on the command line, but running it on PyCharm hides most of the hassle. Actually, I repeated a lot of trial and error, and as a result, I'm a little disappointed that using PyCharm would result in an assassinous procedure.

In the end, PyCharm was the best again.

reference

Mastering type hinting in PyCharm Easy writing documentation in Sphinx with PyCharm (IntelliJ)

[PYTHON] Documentation string reconsidered