sphinx简介

sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发。

新版的Python3文档就是由sphinx生成的,并且它已成为Python项目首选的文档工具,同时它对C/C++项目也有很好的支持。

更多详细特性请参考spinx官方文档

sphinx安装

  1. 需要安装python
  2. pip install sphinx

示例

  1. 新建一个项目

    目录结构如下,

    doc目录使用来存放API文档,

    src目录是用来存放项目的源码

  2. src目录下的源码

    • demo1文件
    主要使用了两种不同的Python注释分格。对于简单的例子和简单的函数以及文档说明,
    使用google style显得更为简洁,
    而对于比较复杂详细的文档说明numpy style更为流行。

coding=UTF-8

class Demo1():

"""类的功能说明"""

def add(self,a,b):
"""两个数字相加,并返回结果"""
return a+b def google_style(arg1, arg2):
"""函数功能. 函数功能说明. Args:
arg1 (int): arg1的参数说明
arg2 (str): arg2的参数说明 Returns:
bool: 返回值说明 """
return True def numpy_style(arg1, arg2):
"""函数功能. 函数功能说明. Parameters
----------
arg1 : int
arg1的参数说明
arg2 : str
arg2的参数说明 Returns
-------
bool
返回值说明 """
return True
``` * demo2文件 ```
注释看起来像Python命令行输入的文档字符串,
主要是用来检查命令输出是否匹配下行的内容,
它允许开发人员在源码中嵌入真实的示例和函数的用法,还能确保代码被测试和工作。
``` ```python

coding=UTF-8

def my_function(a, b):

"""函数功能说明

 >>> my_function(2, 3)
6
>>> my_function('a', 3)
'aaa' """
return a * b
```
  1. 使用sphinx建立API文档项目

    1. 进入到doc目录下

    cd 项目路径/doc

    1. 输入sphinx-quickstart命令,会输出选项

Root path for the documentation [.]: sphinx_demo

Separate source and build directories (y/n) [n]: y

Name prefix for templates and static dir [_]:

Project name: sphinx_demo

Author name(s): sphinx demo

Project version []: 1.0

Project release [1.0]:

Project language [en]: zh_CN

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

doctest: automatically test code snippets in doctest blocks (y/n) [n]: y

intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y

todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y

coverage: checks for documentation coverage (y/n) [n]: y

imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y

mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y

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]:

githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

Create Makefile? (y/n) [y]:

Create Windows command file? (y/n) [y]:

```

```
因为我们需要从Python代码的注释中自动导出API文档,
所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y
如果忘记设置,可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。
选项后面没有输入的,直接按回车键使用默认设置。 选项后面有输入的,按照我的设置即可,
如果不使用中文文档,可以在language配置中使用默认设置。 设置完成之后,可以看到如下的目录结构
``` ![](https://img2018.cnblogs.com/blog/885885/201910/885885-20191022174906524-83463060.png) * 后面如果需要修改配置,在选项source/conf.py文件中修改即可
```python
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax']
``` * 额外的扩展
```text
通过设置conf.py中的extensions,可以为sphinx添加额外的扩展,
如果想要将html文档转换为PDF,只需要先安装扩展,然后再此处添加即可使用。 由于我们的注释代码主要同时支持google style和numpy style,所以我们需要添加一个扩展来支持。
```
```
sphinx.ext.napoleon
```
  1. 为源码生成html文件

    • 修改source/conf.py文件的19-21行

import os

import sys

sys.path.insert(0, os.path.abspath('../../../src')) # 指向src目录

```

* 将命令行切换到doc目录下,执行以下命令
```
sphinx-apidoc -o sphinx_demo/source ../src/ >Creating file sphinx_demo/source\demo1.rst.
>Creating file sphinx_demo/source\demo2.rst.
>Creating file sphinx_demo/source\modules.rst. ```
  1. 清理文件

    cd sphinx_demo
    make clean >Removing everything under 'build'...
  2. 生成html文件

    make html
    
    // 请确保这一步没有输出error和exception
  3. 打开build/html/index.html



  4. 修改API的主题

    打开source/conf.py文件,找到html_theme = 'alabaster',修改即可,sphinx官方提供了几种主题可以进行选择,sphinx主题设置

相关错误解决办法

  • SyntaxError:Non-ASCII character '\xba' in file .....py

    在*.py文件的第一行添加#coding=UTF-8

  • Encoding error:'utf8' codec can't decode byte 0xc0 in position 44:invalid start byte

    确保*.py文件的编码格式为utf-8,通过notepad++可以进行查看,如果不是请修改为utf-8格式

  • 添加sphinx.ext.napoleon后报Exception occurred ....return translator['sphinx'].ugettext(message) KeyError:'sphinx'

    Sphinx1.3,napoleon扩展使用sphinx.ext.napoleon,Sphinx <= 1.2使用sphinxcontrib.napoleon

使用sphinx为python注释生成docAPI文档的更多相关文章

  1. 使用sphinx快速为你python注释生成API文档

    sphinx简介sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的, ...

  2. 利用sphinx为python项目生成API文档

    sphinx可以根据python的注释生成可以查找的api文档,简单记录了下步骤 1:安装 pip install -U Sphinx 2:在需要生成文档的.py文件目录下执行sphinx-apido ...

  3. .Net魔法堂:提取注释生成API文档

    一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和减少后期维护中知识遗失等风险 ...

  4. .net 提取注释生成API文档 帮助文档

    提取注释生成API文档   一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和 ...

  5. 注释生成Api文档

    1.开发背景 最近一直在写dubbo接口,以前总是用word文档写接口描述然后发给别人.现在太多了,而且跟别人对接联调的人家急着用,根本没时间去写word文档.那就想想怎么用doc文档注释自动生成接口 ...

  6. ASP.NET Web API从注释生成帮助文档

    默认情况下,ASP.NET Web API不从Controller的注释中生成帮助文档.如果要将注释作为Web API帮助文档的一部分,比如在帮助文档的Description栏目中显示方法注释中的su ...

  7. 使用Sandcastle 基于代码注释生成接口文档

    一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...

  8. 快速根据注释生成接口文档网页工具——Apidoc的使用教程

    1,安装Node.js的npm工具环境: 如有不懂,请看我的博客:“https://blog.csdn.net/sinat_28371057/article/details/81612661“ 2,n ...

  9. ASP.NET Web API根据代码注释生成Help文档

    使用Visual Studio新建一个ASP.NET Web API项目,直接运行,查看Help文档可以看到如下的API帮助说明 如何在Description中显示描述. 1. 打开Controlle ...

随机推荐

  1. linux系统信息获取和上报

    通过调用shell命令获取系统信息,如cpu个数,cpu/内存磁盘使用情况,网络信息等. #include <stdio.h> #include <stdlib.h> #inc ...

  2. 【HICP Gauss】数据库 数据库管理(shutdown 日志 连接命令)-5

    数据库关闭终止Zengine进程关闭数据库 会导致无法预料的状态 建议shutdown关闭数据库 shutdown 模式1.normal默认 停止新请求 断开等待会话 关闭服务 终止主进程 需要连接发 ...

  3. Python Image库简单处理图像

    直接列举几个常用的函数,可在 http://effbot.org/imagingbook/image.htm 中查看更多相关函数. from PIL import Image import numpy ...

  4. 一些替代Xshell的软件推荐

    FinalShell: 面附上一些截图和官方连接: 官网:http://www.hostbuf.com/ FinalShell是一体化的的服务器,网络管理软件,不仅是ssh客户端,还是功能强大的开发, ...

  5. HashMap扩容死循环问题

    原文:https://blog.csdn.net/Leon_cx/article/details/81911223 下面我们来模拟一下多线程场景下扩容会出现的问题: 假设在扩容过程中旧hash桶中有一 ...

  6. 快捷定位目录 z武器

    z的源码在这里:https://github.com/rupa/z/blob/master/z.sh 1.把源码复制到你的用户目录下的z.sh文件, 2.然后用vim打开.bashrc这个目录,在最后 ...

  7. everything in javascript can act like an object,

  8. test20190904 JKlover

    100+100+100=300.最后十分钟极限翻盘. 树链剖分 给一棵以1为根的有根树,开始只有1有标记. 每次操作可以给某个点打上标记,或者询问从某个点开始向上跳,遇到的第一个有标记的点. 对于 1 ...

  9. ora-00054资源正忙,但指定以nowait方式

    select l.session_id,o.owner,o.object_name from v$locked_object l,dba_objects o where l.object_id=o.o ...

  10. C++中的类所占内存空间总结(转)

    类所占内存的大小是由成员变量(静态变量除外)决定的,成员函数(这是笼统的说,后面会细说)是不计算在内的. 摘抄部分: 成员函数还是以一般的函数一样的存在.a.fun()是通过fun(a.this)来调 ...