Using Sphinx to automatically generate API documents from py source files

Use sphinx according to py Automatic generation of source files API file

1. First create a new directory

 mkdir newdoc
 cd newdoc

3. Then create two subdirectories in the new directory ：

mkdir doc
mkdir src

4. Install the tools used sphinx

pip install sphinx

5. establish html Templates

cd  Project path /doc
sphinx-quickstart

6. Get into source/conf.py Modify the configuration ：

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.napoleon']

7. modify source/conf.py Of documents 19-21 That's ok

import os
import sys
sys.path.insert(0, os.path.abspath('../../../src'))# Modify... According to the actual situation , Point to src Catalog 

8. Execute the creation of the specified source folder API file

sphinx-apidoc -o source ../src/

9. And then make File can

make html

10. Pay attention to code annotation writing specification ：

# -*- coding: utf-8 -*-

class ReStructuredTextStyle:
    '''reStructuredText style 

     use  `` The colon ``  Separate ,
    PyCharm Default style 

    :arg augend:  Augend 
    :type augend: int
    '''

    def __init__(self, augend, name='ReStructuredTextStyle'):
        ''' initialization '''
        self.augend = augend
        self.name = name

    def add(self, addend):
        ''' Add 

        reStructuredText Function of style ,
         The main types are param、type、return、rtype、exception

        :param addend:  Augend 
        :type addend: int
        :returns:  Add the results 
        :rtype: :obj:`int` or :obj:`str`
        :exception TypeError: Addition by str

        >>> reStructredText = ReStructuredTextStyle(augend=10)
        >>> reStructredText.add(10)
        20
        '''
        try:
            if isinstance(addend, str):
                raise TypeError('Addition by str')
            else:
                return self.augend + addend
        except TypeError as e:
            return e