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

This article mainly explains "how to generate python documents from Sphinx". Interested friends may wish to have a look. The method introduced in this paper is simple, fast and practical. Now let the editor take you to learn "how to generate python documents from Sphinx"!

Preface

Sphinx is a document generation tool that supports multiple programming languages. In the process of python project development, it can help developers generate corresponding documentation according to their requirements. Today we will conduct an entry-level practice based on this open source tool.

Installation

Pip3 install sphinx

Environmental preparation

1. Computer with python,pycharm editor installed

two。 Create the relevant project directory, as shown in the following figure, we can create the project folder of document_generate_sphinx, create doc and src folders below, the former is used to store the relevant documents and configuration files generated by sphinx tools, and the latter is used to store your own project source files.

3. Create demo_one.py and demo_two.py files under the src folder, write a few simple classes and test code, and run sphinx-quickstart under the doc directory. The default configuration will generate files that exist in the doc folder as shown in the following figure (except for configuring your own project name, version number, etc., all others are available by default or yes)

3. Next, we can run the command sphinx-apidoc-o.. / doc.. / src/ to generate the rst file from the source code to the doc folder, as shown in the following figure

4. At this point, we can try to run the make html instruction sphinx documentation in the afterlife under the doc directory, but an error occurs here as follows

From the content of the error report, it can be divided into two categories, the first is to remind us that we did not find automodule, and the second is to find that there is no toctree in the modules.rst file.

After practice, we find that to solve the first problem, we need to add the plug-in extensions = ["sphinx.ext.autodoc"] to the conf.py file, and to solve the second problem, we need to add the file path of modules to the index.rst file, as shown below.

5. At this point, we run the make clean&make html directive to clear the previously generated document and generate a new document in the build or _ build folder. Open the index.html file in the html folder of the _ build folder and find the generated document as shown below.

6. In the actual reading of the open source library documentation process, you will find that many of the current python open source documents are unified blue and white alternating theme, in order to make themselves appear more professional, you can replace the current popular theme, before replacing the theme, you need to install the theme library, and do a theme configuration in the conf.py file. As follows

6.1 pip3 install sphinx_rtd_theme

6.2 replace html_theme = "alabaster" in the conf.py file as shown below, and add html_theme_path

7. Rerun the make clean&make html command, and the resulting new document is as follows

8. So far, I have completed a simple document generation example of two program code, but in the actual project, it may also be designed to add and change files in other directories, how to display the files that need to be displayed in the document? Classes such as the addition of changelog, the addition of other files.

For example, here we artificially create a non-py code description file named changelog.rst under the doc directory, and then run the make clean&make html instruction directly to get the following error

From the prompt of the error message, it is because the changelog file has not been placed in toctree, so you need to add the directory of changelog to the index.rst file, as shown in the following figure

9. Run the make clean&make html instruction again, and the compilation is successful, but it is found that after opening the index in the document directory, the display is particularly ugly. I suggest you delete it. The original picture is as follows.

10. Delete the red part of the index.rst file, below the left picture, and then compile again to generate a new document, you can find that without the index module, it appears simple and clean, as shown on the right below.

11. If you change the file that the source code needs to show during the development process, you need to rerun the directive sphinx-apidoc-o.. / doc.. / src/ that generates the rst file

For example, in order to demonstrate, we renamed demo_one.py and demo_two.py in the original src file to animal_attack.py and dog_aonstan.py files, and rewrote some code, then we need to rerun the above directive and delete the original rst file and change the module name in the modules.rst file, as shown in the following figure

Run the make clean&make html instruction again and find that the compilation is successful and the document has updated the relevant modules and contents. in addition, someone will say what to do if the functions that need to be shown in the document can be linked to the source code.

twelve。 The document shows the source code of the function link. Add the "sphinx.ext.viewcode" module to extensions in the conf.py file and regenerate the document as follows

At this point, I believe you have a deeper understanding of "how Sphinx generates python documents". You might as well do it in practice. Here is the website, more related content can enter the relevant channels to inquire, follow us, continue to learn!

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.