当前位置:网站首页>Sphinx first taste

Sphinx first taste

2020-12-07 13:01:22 The clouds are deep and boundless

We can often see this kind of doc file , Simple and generous . As a reading, it can be said that it is enjoyable to look at

So can I make one of these by myself doc Well , I think it can be , Let's try with me !

https://robomaster-dev.readthedocs.io/zh_CN/latest/python_sdk/beginner_multi_robot.html

Recently, a friend wants to be a big Xinjiang EP vehicle , I offer some advice , Looking at Dji Of SDK, I'll take this as a demonstration .

https://iridescent.ink/HowToMakeDocs/Basic/Sphinx.html
https://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html

We achieve this goal , It uses Sphinx:

Sphinx It's a documentation tool , It makes it easy to write clear and beautiful documents , from Georg Brandl stay BSD Develop under license . New version of the Python Documents are created by Sphinx Generated , And it has become Python Project preferred documentation tool , At the same time, it's right for C/C++ The project also has good support ; And plans to add special support to other development languages . Of course, this site also uses Sphinx Generated , It uses reStructuredText! Sphinx Development continues . The following is a list of its good features , These characteristics are in Python It is reflected in official documents :

  • Rich output formats : Support HTML ( Include Windows Help document ), LaTeX ( You can print PDF edition ), manual pages(man file ), Pure text
  • Complete cross references : Semantic tags , And it can automatically link functions , class , a citation , Terms and similar pieces of information
  • Clear hierarchy : You can easily define the document tree , And automatically link peers / Parent / The subordinate article
  • Beautiful automatic indexing : Can automatically generate beautiful module index
  • Precise syntax highlighting : be based on Pygments Automatically generate syntax highlighting
  • Open expansion : Support automatic testing of code blocks , And includes Python The readme document for the module (API docs) etc.

Sphinx Use reStructuredText As a markup language , Can enjoy Docutils by reStructuredText Analysis provided , Conversion and other tools .

This is the latest Python file

https://docs.python.org/zh-cn/3/

First, create a folder , In order to avoid polluting the environment

Take a look at the catalogue first

stay pip

Whether separation source and build Catalog ( Input y, Choose separation , Easy to manage )

Welcome to use Sphinx 3.3.0 Quick start utility .

Please enter the following settings ( Just press Enter

Accept the default value ( If you give in brackets ).

Selected root path :.

You have two choices to place Sphinx Output build directory .

You can use the directory in the root path “ _build”, It can also be used alone

In the root path “ Source ” and “ structure ” Catalog .

There are some hints , Press it yourself

 The project name will appear in multiple places in the generated document .
> Project name :yunswj
> Author's name :yunswj
> Project release []:0.1

 If you want to write a document in a language other than English ,
 You can choose a language from the language code here . The sphinx 
 Translate the text it generates into the language .

 List of supported code , Please see the 
https://www.sphinx-doc.org/zh-CN/master/usage/configuration.html#confval-language.
> Project language [zh]:

 create a file C:\ Users \ yunswj \ Desktop \ Sphinx \ source \ conf.py.
 create a file C:\ Users \ yunswj \ Desktop \ Sphinx \ source \ index.rst.
 create a file C:\ Users \ yunswj \ Desktop \ Sphinx \ Makefile.
 create a file C:\ Users \ yunswj \ Desktop \ Sphinx \ make.bat.

 complete : The initial directory structure has been created .

 Now? , You should fill in the master file C:\ Users \ yunswj \ Desktop \ Sphinx \ source \ index.rst And create other documents 
 Source file . Use Makefile Build documentation , As shown below :
    Make the builder 
 among “ Builder ” Is one of the supported builders , for example html,latex or linkcheck.

Project name

Editor's name

Version number of the document

Project language , I chose default . Just go back

These files will be generated .

This is the generative structure

  • build: Used to store through make html The directory that generates the document web page file
  • source: Store the source file used to generate the document
  • conf.py: Sphinx Configuration file for
  • index.rst: Main document
config.py Details of 
https://www.sphinx-doc.org/en/master/usage/configuration.html

This is the configuration file. You can see that it is consistent with the content when I created the file

https://www.sphinx-doc.org/en/master/usage/configuration.html

  • project
  • Recorded project name .
  • author
  • Name of the author of the document . The default value is 'unknown'.
  • copyright
  • Style copyright notice .'2008, Author Name'
  • version
  • Main project version , Used in substitution |version|. for example , about Python file , It may be similar to 2.6.
  • release
  • Full project version , Used for replacement |release|HTML Templates , For example, in HTML In the template . for example , about Python file , It may be similar to 2.6.0rc1.

Display error , It's smart to remind me to use .\ This grammar

The type that can be output , Some can't be exported . Lack of things

.\make file type

 function Sphinx v3.3.0
 Make output directory ... complete 
 establish [mo]: Out of date 0 individual po The purpose of the document 
 establish [html]: Out of date 1 Target of source files 
 Update the environment :[ New configuration ] Added 1 individual , To change the 0 individual , Deleted 0 individual 
 Reading sources ... [100%] Indexes 
 Looking for outdated Archives ... Can't find 
 Pickling environment ... complete 
 Check consistency ... complete 
 Preparing documents ... complete 
 Write output ... [100%] Indexes 
 Build index ... genindex complete 
 Write other pages ... search complete 
 Copy static files ... complete 
 Copy extra files ... complete 
 In English ( Code :en) Dumping search index ... complete 
 List of dumping targets ... complete 
 Build success .
HTML The page is located at build \ html in .

The compiled directory looks like this

There are three of them html file , Open it all and have a look

These are the three open web documents

Then I want to preview the document automatically when I'm finished , To do ? Of course

This is the location of my browser , If you are chrome, You can copy my address directly

C:\Program Files\Google\Chrome\Application

Add environment variables to the browser directory , Find... Yourself

stay :end and popd Code in the middle

:end

        REM ----------------------------------------------
        REM Added by Yunswj - Auto open build file
        REM ----------------------------------------------

        if "%1" == "html" (
        chrome build/html/index.html
        )

popd

To such

For the first time

powershell Still can't

use cmd Open normal , This powershell In fact, more shell some

here , We're going to take a look at hosting and using his home theme

https://readthedocs.org/

I use Github Log on to the

It's a hosting platform , Ba Shi is very

https://readthedocs.org/projects/yunswj-demo/

These instructions are generated by themselves doc

This is generated by default doc

This is the source code

Cloud server compilation , It's a little easy to use

Detailed settings

You can import your own documents ( On-line )

You can see that there are many detailed options

https://readthedocs.org/dashboard/import/manual/?

You can import by address like this

https://github.com/readthedocs/template
pip install sphinx_rtd_theme

I don't trust here either , Let's start with the theme

install

success

# for using Read the Docs theme
import sphinx_rtd_theme
# html_theme = 'sphinxdoc'
html_theme = 'sphinx_rtd_theme'

#html_theme_path = []
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

No change in recompiling

In order to automatically preview , use cmd

Or the theme has not changed , And then it's going to be solved

Support markdown file 、 Change document subject

Spinx Itself does not support .md File generation document , We need to use third-party libraries recommonmark convert . First run the following commands to install recommonmark And sphinx_rtd_theme library .

pip install recommonmark

pip install sphinx_rtd_theme

Install well , stay conf.py Modify the following two configurations in :

source_suffix = ['.rst', '.md', '.MD']
html_theme = 'sphinx_rtd_theme'

And the new :

source_parsers = {
    '.md': CommonMarkParser,
    '.MD': CommonMarkParser,
}
https://sphinx-doc-zh.readthedocs.io/en/latest/tutorial.html

There's a lot of this one , The next one goes on to write

This article is from WeChat official account. - The cloud is deep and traceless (TT1827652464) , author : The cloud is deep and traceless

The source and reprint of the original text are detailed in the text , If there is any infringement , Please contact the yunjia_community@tencent.com Delete .

Original publication time : 2020-12-02

Participation of this paper Tencent cloud media sharing plan , You are welcome to join us , share .

版权声明
本文为[The clouds are deep and boundless]所创,转载请带上原文链接,感谢
https://chowdera.com/2020/12/20201207125830419z.html