sphinx自动化文档

谁践踏了优雅 2022-07-14 23:57 424阅读 0赞

# sphinx自动化文档 #

sphinx是python的御用自动化文档模块，通过提取代码中的文档注释（docstring）来生成代码文档，还是很方便的，你看到很多python官方教程，其实都是sphinx生成的，比如数据分析的pandas:[http://pandas.pydata.org/pandas-docs/stable/][http_pandas.pydata.org_pandas-docs_stable]  
废话不多说，下面开始。  
需要注意的是，我使用的python3.5，sphinx1.4.

# 安装sphinx和sphinx\_bootstrap\_theme主题 #

安装方法可以使用pip方法安装，也可以先将源码包下载后使用setup安装。个人觉得sphinx\_bootstrap\_theme比sphinx中包含的几个主题要好看一些。  
sphinx的官网地址:[http://www.sphinx-doc.org/en/1.4.8/][http_www.sphinx-doc.org_en_1.4.8]  
sphinx\_bootstrap\_theme主题地址:[http://ryan-roemer.github.io/sphinx-bootstrap-theme/][http_ryan-roemer.github.io_sphinx-bootstrap-theme]

# 建立sphinx项目 #

在代码目录下安装shift+鼠标右键，打开cmd窗口，我的目录地址是 `E:\pycharm`  
然后依次输入如下命令，注意，如果没有输入直接回车，则是使用默认选型

E:\pycharm> sphinx-quickstart
    > Root path for the documentation [.]: doc  # 在当前目录下新建doc文件夹存放sphinx相关信息
    > Separate source and build directories (y/n) [n]:   # 默认，直接回车
    > Name prefix for templates and static dir [_]: 
    > Project name: python123   # 输入项目名称
    > Author name(s): 123   # 作者
    > Project version: 1.0  # 项目版本
    > Project release [1.0]:
    > Project language [en]:   # 默认，回车
    > Source file suffix [.rst]: 
    > Name of your master document (without suffix) [index]:
    > Do you want to use the epub builder (y/n) [n]:
    > autodoc: automatically insert docstrings from modules (y/n) [n]: y  # 这个很重要，输入y
    > doctest: automatically test code snippets in doctest blocks (y/n) [n]:
    > intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
    > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
    > coverage: checks for documentation coverage (y/n) [n]:
    > pngmath: include math, rendered as PNG images (y/n) [n]:
    > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
    > ifconfig: conditional inclusion of content based on config values (y/n) [n]:
    > viewcode: include links to the source code of documented Python objects (y/n) [n]: y  # 很重要，输入y，表示将源码也放到文档中，你看很多python的模块的文档，其实都是包含代码的。
    > Create Makefile? (y/n) [y]:
    > Create Windows command file? (y/n) [y]:
    
    # 之后会在doc目录下生成如下文件
    E:.
    │  conf.py
    │  index.rst
    │  make.bat
    │  Makefile
    │
    ├─_build
    ├─_static
    └─_templates

# 生成apidoc #

还是在刚才的目录下 `E:\pycharm` 打开cmd

# 对当前目录的每一个文件夹及子文件夹生成一个rst文件，对应python的包，存放在./doc目录下
    sphinx-apidoc -o ./doc/ .
    
    # 之后会在doc文件夹下看到很多刚才生成的rst文件
    E:.
    │  ahp_model_ys.rst
    │  conf.py
    │  config.rst
    │  control_all_data_and_process.rst
    │  data_etl.rst
    │  dynamic_proc.rst
    │  ex_data.oracle_imp_exp.rst
    │  ex_data.rst
    │  index.rst
    │  keywords.rst
    │  log_ys.rst
    │  make.bat
    │  Makefile
    │  modules.rst
    │  predict_by_rule_ys.rst
    │  similar_prison_ys.rst
    │  tools_py.backup_ys.rst
    │  tools_py.cmd_py.rst
    │  tools_py.database.rst
    │  tools_py.email_ys.rst
    │  tools_py.linux.rst
    │  tools_py.rst
    │  tools_py.sched_py.rst
    │  tools_py.time_py.rst
    │  trace_sql_info.rst

# 修改conf #

进入doc目录，修改conf.py文件。

# 1.增加搜索目录
    # 找到 #sys.path.insert(0, os.path.abspath('.'))，去掉注释并修改为
    sys.path.insert(0, os.path.abspath('..'))
    
    # 2.修改主题
    # 在文件的开头导入刚才安装的主题
    import sphinx_bootstrap_theme
    # 找到html_theme，修改为
    html_theme = 'bootstrap'
    # 找到html_theme_path，修改为
    html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
    # 找到html_theme_options，修改为
    html_theme_options = {  
        'navbar_title': "你的项目名称",  
        'globaltoc_depth': 2,  
        'globaltoc_includehidden': "true",  
        'navbar_class': "navbar navbar-inverse",  
        'navbar_fixed_top': "true",  
        'bootswatch_theme': "united",  
        'bootstrap_version': "3",  
    }

sphinx\_bootstrap\_theme的参数调节请参考其官方文档。

# 修改index.rst #

打开doc目录下的index.rst文件，你可以在这里写上一起其他的欢迎信息，简要说明，或者注意事项。需要注意的是，sphinx的语法和markdown差不多，使用空行表示换行。

在 :maxdepth: 2 下面增加modules.rst，表示目录

最后的我修改的样子如下，注意要去掉括号里面的注释。

.. python123 documentation master file, created by
     sphinx-quickstart on Tue Oct 25 14:30:26 2016.
     You can adapt this file completely to your liking, but it should at least
     contain the root `toctree` directive.
    
    你好啊，这是一级标题
    ==================  （注意，可以用=或者-表示标题，只要长度大于标题就可以了）
    
    空一行，这里写些其他内容，简介或者注意事项。
    
    当然你也可以加入代码，后面加两个冒号，然后缩进 :: import pandas as pd
     pd.DataFrame()
    
    更多格式，可以参考：
    http://blog.csdn.net/jianhong1990/article/details/8256598
    
    Contents:
    
    .. toctree::
     :maxdepth: 2 （目录树深度，不要展开太多）
    
     modules.rst （这里空一行加入目录，当然也可以加其他rst。注意要和上面的平级，）
    
    Indices and tables ==================
    
    * :ref:`genindex`
    * :ref:`modindex`
    * :ref:`search`

# 修改modules.rst #

# 将modules.rst第一行的点号修改为 '显示目录'，当然可以不改。
    # 第一行的等号多写几个，长度大于第一行
    # 树深度改为3
    
    显示目录
    =========
    
    .. toctree::
       :maxdepth: 3

# 编译 #

在doc目录下打开cmd，执行 `make html`，过一会就可以在 `doc\_build\html`目录下看到编译生成的网页文件了。

# 严重的排版问题 #

由于sphinx使用空行表示换行，这就会导致，如果想要在网页端可到好看的结果，那么代码文件中的注释就需要很多空行，如果想在代码文件中把注释写得好看点，那么网页端排版可能就不好看了。  
另一个问题是缩进问题，一个大问题总会分解成几个小问题吧，或者一个问题有几个小步骤，这时候分几点然后缩进排版是很正常的。  
比如下面的源码中的注释：

为了保持网页端的排版好看，我可能需要这样写注释。
    
    上面空了一行，否则你在源码中看到的换行，在网页端其实并没有换行。
    
    又比如缩进问题：
    
        又要空一行，真的是浪费啊，而且也不是那么好看了。如果这里缩进，就会变成列表了，其实在网页端是不好看的。
    
        不信你试试

但是在正常的情况下，你肯定不会写这么多空行吧，真实的情况只有在两个段落差异比较大的情况才会这样换行吧，下面是更多见的注释情况吧

为了保持网页端的排版好看，我可能需要这样写注释。
    一般情况下谁没事会经常空一行表示换行呢？直接回车就行了嘛，代码已经不好看了，注释还不能好看。
    (下面空一行，表示两个段落的分割)
    
    又比如缩进问题：
        我这里不想空一行再缩进，想要直接缩进，就像这样子。
        可是它会变成列表那样子，排版上其实是不好看的。
        不信你试试

那么有没有办法既能兼顾代码注释的美观，又能使生成的网页比较好看呢？  
答案是不能的，只能曲线处理，就是牺牲代码注释一点点的美观，换取不要写那么多空行。

## 使用特殊的换行标记 ##

比如在注释中，每一行的末尾都加入``，这样生成网页后，将所有网页的这个``标记替换成``实现换行。 
虽然不是高明，但是也还过得去。 
缩进问题，比如在行首加上`.`号防止被识别为列表缩进，然后空4个空格接着写注释，对生成的网页文件，将这个（点号+4个空格）替换成网页能识别的空格`&nbsp`即可。 
那么代码注释就会变成这样了：

为了保持网页端的排版好看，我可能需要这样写注释。 
 在每一行的后面都加一个 ，这样就可以后期直接修改网页源码使之变成换行符
 (下面空一行，表示两个段落的分割) 
 
 又比如缩进问题： 
 . 我在前面加上点号，然后几个空格，后期可以直接对网页源码修改为几个空格即可实现缩进。
 . 不信你试试

## 使用块缩进 ##

上面的方法虽然可行，但是步骤还是多了写，而且需要在生成网页后批量修改网页源代码。  
有一个比较笨，但是也还不错的方法，就是所用块缩进，也就是在每一行起始用`|`（竖线+空格）表示块，这样就间接解决了换行问题，唯一不足的地方是，没有那么好看了。  
修改后的注释是这样的：

当然，如果是函数的注释，而且注释也不长，就没必要搞这么麻烦了，使用空行可能会方便一些。  
看情况吧。

# 参考 #

[http://www.sphinx-doc.org/en/1.4.8/][http_www.sphinx-doc.org_en_1.4.8]  
[http://sphinx-bootstrap-theme.readthedocs.io/en/latest/][http_sphinx-bootstrap-theme.readthedocs.io_en_latest]  
[http://blog.csdn.net/weishantc/article/details/46729103][http_blog.csdn.net_weishantc_article_details_46729103]  
[http://blog.csdn.net/handsomekang/article/details/46830083][http_blog.csdn.net_handsomekang_article_details_46830083]  
[http://blog.csdn.net/jianhong1990/article/details/8256598][http_blog.csdn.net_jianhong1990_article_details_8256598]  
[http://pm.readthedocs.io/doc/sphinx.html][http_pm.readthedocs.io_doc_sphinx.html]

[http_pandas.pydata.org_pandas-docs_stable]: http://pandas.pydata.org/pandas-docs/stable/
[http_www.sphinx-doc.org_en_1.4.8]: http://www.sphinx-doc.org/en/1.4.8/
[http_ryan-roemer.github.io_sphinx-bootstrap-theme]: http://ryan-roemer.github.io/sphinx-bootstrap-theme/
[http_sphinx-bootstrap-theme.readthedocs.io_en_latest]: http://sphinx-bootstrap-theme.readthedocs.io/en/latest/
[http_blog.csdn.net_weishantc_article_details_46729103]: http://blog.csdn.net/weishantc/article/details/46729103
[http_blog.csdn.net_handsomekang_article_details_46830083]: http://blog.csdn.net/handsomekang/article/details/46830083
[http_blog.csdn.net_jianhong1990_article_details_8256598]: http://blog.csdn.net/jianhong1990/article/details/8256598
[http_pm.readthedocs.io_doc_sphinx.html]: http://pm.readthedocs.io/doc/sphinx.html