如何给一个GUI软件写document？ Sphinx

Sphinx使用总结

第一步：

pip install sphinx
​
pip install sphinx_rtd_theme

第二步：

cd project

第三步：

sphinx-quickstart

第四步：配置conf.py

import os
import sys
sys.path.insert(0, os.path.abspath(r'D:\PythonProject\code'))
​
html_theme = 'sphinx_rtd_theme'
extensions = ['sphinx.ext.autodoc']

第五步： 在doc目录下执行

sphinx-apidoc -o source "D:/PythonProject/code"

第六步：修改index.rst 文件

.. toctree::
   :maxdepth: 2
   :caption: Contents:
​
   modules
​
​
​
Indices and tables
==================
​
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

第七步：在doc目录下执行make html，就会生成html文档，打开html文档，就可以了【注意脚本一定要放在main里边】

make clean
​
make html

======================

如何给一个GUI软件写document？

how to write the document for a GUI software

如何给Python项目写文档？

有两种方案：

1、pydoc

不推荐

2、Sphinx

（1）pip install sphinx

（2）pip install sphinx_rtd_theme

test1.py

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

class Test1():
    '''
    我是测试类，负责测试
    '''
    def hello(self):
        '''
        负责打印Hello， 人人可以学Python
        :return: 
        '''
        print("人人可以学Python")
    def renren(self):
        '''
        测试Sphinx自动生成文档
       
        :return: 
        '''
        print("自动生成文档")
class Test2():

    def test_2(self):
        '''
        我也不知道写什么好，反正我们这里是用来写文档的
        :return: 
        '''
        print("文档自动生成测试2")
    def renren_2(self):
        '''
        所以我们开发的时候就应该在这里写好文档，然后用Sphinx自动生成

        :return: 
        '''
        print("自动生成文档2")

test2.py

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

def init_test():
    '''
    用于初始化项目测试，不需要任何参数
    :return: 
    '''
    print("初始化项目")


def start():
    '''
    启动项目入口，
    :return: 
    '''
    test(3)

def test(v):
    '''
    项目运行主要函数，需要传入一个参数\n
    v:<int>
    :return: 
    '''

    print(v)

（3）创建文件夹doc：mkdir doc；cd doc；执行sphinx-quickstart，进入引导，根据需要选择yes或者no

zh_CN

（4）执行sphinx-quickstart引导程序只会生成一个index.rst

sphinx-quickstart

（5）配置conf.py

        

import os
import sys
sys.path.insert(0, os.path.abspath(r'D:\PythonProject\code'))

#
html_theme = 'sphinx_rtd_theme'

extensions = ['sphinx.ext.autodoc']

总结：

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath(r'D:\PythonProject\code'))


# -- Project information -----------------------------------------------------

project = 'fff'
copyright = '2022, f'
author = 'f'

# The full version, including alpha/beta/rc tags
release = '1'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

（6）

 在doc目录下执行sphinx-apidoc -o source  “file_directory”，其中file_directory是指你需要文档化的目录，

sphinx-apidoc -o source "D:/PythonProject/code"

（7） 修改index.rst 文件

.. fff documentation master file, created by
   sphinx-quickstart on Tue Mar 29 13:30:33 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to fff's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

（8）在doc目录下执行make html，就会生成html文档，打开html文档，就可以了

make clean

make html

 D:\PythonProject\code\doc\build\html\index.html

大功搞成

-----DEBUG的过程----

sphinx-apidoc 生成的index.html里边是空的

sphinx WARNING: Unknown directive type "automodule".

可以了！！！

================

有两个疑问：

1、为什么类旁边的函数没有显示出来？

这样做  就可以了

 

================

需要注意的有两点：

0、每个modul（文件夹）下，要创建一个"__init__.py"  将文件夹升级为  modul

1、引用的时候要这样   form modul.submodul import *

2、py文件名中不要出现“-”或者“_”

=====

mkdir doc

cd doc

sphinx-quickstart

QuanSystem
XXXX
V0.1.0
zh_CN

conf.py   修改

import os
import sys
sys.path.insert(0, os.path.abspath(r'D:\PythonProject\QTNLS'))

extensions = ['sphinx.ext.autodoc']

html_theme = 'sphinx_rtd_theme'

sphinx-apidoc -o source "D:/PythonProject/QTNLS"

modules

make html