当前位置 主页 > 网站技术 > 代码类 >

    Python Sphinx使用实例及问题解决

    栏目:代码类 时间:2020-01-17 18:06

    这篇文章主要介绍了Python Sphinx使用实例及问题解决,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下

    描述

    使用 pip 安装sphinx后,按照教程建立了一个新的py文件,如下

    # run.py
    def run(name):
      """
      this is how we run
      :param name name of people who runs
      """
      print(name, 'is running')

    随后新建一个目录,使用 sphinx-quickstart 新建了sphinx环境,此时目录结构如下:

    - doc
      - Makefile
     - build/
     - make.bat
     - source/
    - run.py

    此时进入 source目录,在conf.py 中添加文件路径,如下:

    import os
    import sys
    sys.path.insert(0, os.path.abspath('../..'))

    然后在 doc 下执行下面命令:

    make html
    or
    sphinx-build -b html ./doc/source ./doc/build

    发现两个命令都可以正常生成文档的模版,但并没有生成注释;即有生成的html,但没有代码的注释/API文档

    尝试解决

    开始以往是版本不一致,就重新建了virtualenv,还是不行;

    使用了一个docker镜像,重试,结果是同样的错误

    尝试看非官方的教程,发现还需要更改 source 下的 index.rst;

    例如我们的代码文件是 run.py ,需要把他加到 index.rst中,如下(run就是模块名称):

    API
    ===
    .. automodule:: run
      :members:

    再次执行,发现还有错,只不过提示不一样了:提示

    Unknown directive type “automodule” or “autoclass”

    谷歌之,发现还要改一个配置的地方;位于 conf.py 里,增加一个扩展……如下:

    extensions = [
        'sphinx.ext.autodoc'
    ]

    此处参考了 https://stackoverflow.com/questions/13516404/sphinx-error-unknown-directive-type-automodule-or-autoclass

    再次尝试,终于成功了…

    以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持IIS7站长之家。