Shulou(Shulou.com)06/02 Report--

This article will explain in detail how to use Sphinx to write documents for Python code. The editor thinks it is very practical, so I share it with you as a reference. I hope you can get something after reading this article.

Python code can include documentation in the source code. This approach relies by default on docstring, which is defined in three quotation marks. Although the value of documentation is great, it is common that code without adequate documentation. Let's walk through a scenario to understand the power of good documentation.

You've had enough of asking you to implement the Fibonacci series in a whiteboard technical interview. You go home and write a reusable Fibonacci calculator in Python, using floating-point techniques to achieve O (1) complexity.

The code is simple:

The Fibonacci series is a geometric sequence rounded to the nearest integer, which is one of my favorite little-known mathematical facts. )

As a good person, you can open source the code and put it on PyPI. The setup.py file is simple:

Import setuptools setuptools.setup (name='fib', version='2019.1.0', description='Fibonacci', py_modules= ["fib"],)

However, code without documentation is useless. Therefore, you can add docstring to the function. One of my favorite docstring styles is the "Google" style. The tag is lightweight and good when it is placed in the source code.

Def approx_fib (n): "" Approximate Fibonacci sequence Args: n (int): The place in Fibonacci sequence to approximate Returns: float: The approximate value in Fibonacci sequence "" #...

But the documentation for the function is only half the success. Normal documentation is important for situational code usage. In this case, the situation is an annoying technical interview.

There is a way to add more documents, and the way for professional Python people is usually to add rst files (short for reStructuredText) to docs/. So the docs/index.rst file ends up looking like this:

Fibonacci= Are you annoyed at tech interviewers asking you to implementthe Fibonacci sequence?Do you want to have some fun with them?A simple:code: `pip install people `is all it takes to tell them to,um,fib off. .. Automodule:: fib: members:

We're done, right? We have put the text in the file. People should be watching it.

Make Python documents more beautiful

To make your documents look more beautiful, you can use Sphinx, which aims to make beautiful Python documents. These three Sphinx extensions are particularly useful:

Sphinx.ext.autodoc: get documents from within the module

Sphinx.ext.napoleon: docstring that supports Google style

Sphinx.ext.viewcode: package the ReStructured Text source code with the generated document

To tell Sphinx what to generate and how to generate it, we configure an auxiliary file in docs/conf.py:

Extensions = ['sphinx.ext.autodoc',' sphinx.ext.napoleon', 'sphinx.ext.viewcode',] # the name of the entry point, without the .rst extension. # conventionally, the name is indexmaster_doc = "index" # these values are all used in the generated document. Usually, release is the same as version, but sometimes we have releases with rc tags. Project = "Fib" copyright = "2019, Moshe Zadka" author = "Moshe Zadka" version = release = "2019.1.0"

This file allows us to publish the code using all the metadata we need and pay attention to the extension (the comments above explain how). Finally, to ensure that the documents we want are generated, use Tox to manage the virtual environment to ensure that we generate the documents smoothly:

[tox] # by default, `.tox` is this directory. # place it in a non-point file to open the resulting document from the # open dialog box of the # file manager or browser, which sometimes hides the point file. Toxworkdir = {toxinidir} / build/tox [testenv:docs] # run `sphinx` from the `docs` directory to ensure that it does not pick up any spurious files that may enter the # virtual environment under the top directory or other artifacts under the `docs` directory. The only dependency of changedir = docs# is `sphinx`. # if we are using separately packaged extensions, # We will specify them here. # it is better to specify a specific version of sphinx. Deps = sphinx# this is the `sphinx` command used to generate HTML. # in other cases, we may want to generate PDF or e-books. Commands = sphinx-build-W-b html-d {envtmpdir} / doctrees. {envtmpdir} / html# We use Python 3.7. # Tox sometimes tries to detect testenv automatically based on its name, # but `docs` doesn't give a useful clue, so we have to make it clear. Basepython = python3.7

Now, whenever you run Tox, it will generate beautiful documentation for your Python code.

It's good to write documents in Python.

As Python developers, the tool chain we can use is great. We can start with docstring, add a .rst file, and then add Sphinx and Tox to beautify the results for the user.

On "how to use Sphinx to document Python code" this article is shared here, I hope the above content can be of some help to you, so that you can learn more knowledge, if you think the article is good, please share it out for more people to see.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.