Sphinx生成python文档示例图文解析

目录
  • 前言
  • 结 语

前言

Sphinx是一款支持多种编程语言的文档生成工具，在python项目开发过程中，可以帮助开发者根据需求生成相应的说明文档，拿今天我们就基于该开源工具进行一个入门的实践。

安装

pip3 install sphinx

环境准备

1. 安装python，pycharm编辑器的电脑

2. 创建相关的项目目录，如下图所示，我们可以创建document_generate_sphinx的项目文件夹，在下面分别创建doc和src文件夹，前者用来存放sphinx工具生成的相关文档和配置文件，后者用来存放自己的项目源码文件。

3. 在src文件夹下创建demo_one.py和demo_two.py文件，并写上简单的几个类和测试代码，在doc目录下运行sphinx-quickstart，一路默认配置下来会生成如下图所示存在于doc文件夹中的文件（这其中除了要配置自己的项目名称，版本号等内容外，其他均默认或者yes即可）

3. 接下来，我们可以运行sphinx-apidoc -o ../doc ../src/ 命令将源码生成rst文件到doc的文件夹下，如下图

4. 到此，我们就可以尝试 在doc目录下 运行make html指令来生sphinx说明文档了，但是在这里发生了报错如下

　　从报错的内容来看分为两类，第一个是在提示我们没有发现automodule，第二个是发现modules.rst文件中没有toctree。

经过实践我们得到解决第一个问题需要在conf.py文件中添加上extensions = ["sphinx.ext.autodoc"]插件即可，解决第二个问题，需要在index.rst文件中添加上modules的文件路径，如下所示

5. 此时，我们再去运行make clean&make html指令，可以清除之前生成的文档，生成新的文档在build或者_build文件夹中，打开_build文件夹html文件夹中的index.html文件可以发现生成的文档如下图

6. 在实际阅读开源库的说明文档过程中会发现，目前python的很多开源文档都是统一的蓝白交替的主题，为了让自己显得更专业，可以为其替换一下目前流行的主题，在替换主题前，需要安装一下主题库，并在conf.py文件中做一个主题配置。如下

　　6.1 pip3 install sphinx_rtd_theme

　　6.2 在conf.py文件中将 html_theme = "alabaster"更换如下图，再添加上html_theme_path

7. 重新运行make clean&make html命令，生成的新文档说明如下

8. 至此，完成了一个简单的两个程序代码的文档生成示例，但是在实际项目中，可能还设计到其他目录下文件的添加和变更，怎样把需要展示的文件展示到文档中？类如changelog的添加，其他文件的添加。

　　比如，这里在doc目录下直接人为创建一个非py代码的说明文件，命名为changelog.rst，然后直接运行make clean&make html指令，得到了如下报错

　　从报错内容的提示来看，是因为changelog文件没有被放到toctree中，所以需要在index.rst文件中添加上changelog的目录，如下图所示

9. 再次运行make clean&make html指令，编译顺利成功，但是发现打开文档目录中index后，显示特别丑，个人建议可以将其删掉，原图如下

10. 删除掉index.rst文件中红色部分，如下左图，然后再次编译生成新的文档，可以发现没有了索引模块，显得简单干净，如下右图所示。

11. 如果在开发过程中更改了源代码需要展示的文件，需要重新运行生成rst文件的指令 sphinx-apidoc -o ../doc ../src/

　　比如，为了示范，我们将原来src文件中的demo_one.py 和 demo_two.py分别更名成 animal_attack.py和dog_aonstan.py文件，并重新写了一些代码，那么就需要重新运行上述指令并删除原来的rst文件并更改modules.rst文件中的module名称，如下图

　　再次运行make clean&make html指令，发现编译成功，文档也更新了相关模块和内容，另外会有人说，如果需要在文档中展示的函数能够链接到源码，需要怎么做，这里很简单。

12. 文档展示函数链接源码，在conf.py文件中extensions中添加"sphinx.ext.viewcode"模块 重新生成文档如下

结 语

　　至此，Sphinx文档生成的简单入门示例就完成啦，如果需要更深入的研究和探讨，大家可以参考sphinx的官方文档。

以上就是Sphinx生成python文档示例图文解析的详细内容，更多关于Sphinx生成python文档的资料请关注我们其它相关文章！

赞 (0)

相关推荐

  • sphinx使用及其简单配置方法

    sphinx使用 进入你要创建文档的目录,例如要创建在目录/home/wwwroot/doc下 cd /home/wwwroot/doc 开始使用向导创建你的文档项目 sphinx-quickstart 程序会提示输入一些选项,如输入根目录,大部分使用默认选项,直接按回车即可. 复制代码 代码如下: Enter the root path for documentation. > Root path for the documentation [.]: //输入跟目录,直接回车 You have

  • Python Sphinx使用实例及问题解决

    这篇文章主要介绍了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 ru

  • 深入解析php之sphinx

    <?php //参数筛选 //筛选cat_id=2$cl->SetFilter("cat_id",array(2));//仅在id为1.3.7的子论坛中搜索$cl->SetFilter("forum_id",array(1,3,7)); //范围筛选//筛选发布时间为今天,参数为int时间戳$cl->SetFilterRange("starttime",123,124);//筛选价格$cl->SetFilterRan

  • Yii框架中sphinx索引配置方法解析

    本文实例讲述了Yii框架中sphinx索引配置方法.分享给大家供大家参考,具体如下: 请先将var/test/documents.sql导入数据库,并配置好以下的MySQL用户密码数据库 #源定义 source mysql { type = mysql sql_host = localhost sql_user = root sql_pass = root sql_db = yii2 sql_port = 3306 sql_query_pre = SET NAMES utf8 sql_query

  • sphinxql如何得到结果数及show meta的详细说明

    mysql:select count(*) from main_index; 但是这个在这里却报语法错误. 第一种方法:查文档得:Aggregate functions (AVG(), MIN(), MAX(), SUM()) in column list clause are supported. Arguments to aggregate functions can be either plain attributes or arbitrary expressions. COUNT(*)

  • sphinx增量索引的一个问题

    但最近发现增量的总是搜索不到,今天看了下运行日志,有如下提示: [Sun Apr 17 19:30:01.876 2011] [ 3400] WARNING: rotating index 'news_delta': cur to old rename failed: rename /dev/shm/sphinx/data/news_delta.spa to /dev/shm/sphinx/data/news_delta.old.spa failed: No such file or direc

  • Sphinx生成python文档示例图文解析

    Sphinx生成python文档示例图文解析

    目录 前言 结 语 前言 Sphinx是一款支持多种编程语言的文档生成工具,在python项目开发过程中,可以帮助开发者根据需求生成相应的说明文档,拿今天我们就基于该开源工具进行一个入门的实践. 安装 pip3 install sphinx 环境准备 1. 安装python,pycharm编辑器的电脑 2. 创建相关的项目目录,如下图所示,我们可以创建document_generate_sphinx的项目文件夹,在下面分别创建doc和src文件夹,前者用来存放sphinx工具生成的相关文档和配置

  • java集成开发SpringBoot生成接口文档示例实现

    java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • 利用Java Apache POI 生成Word文档示例代码

    最近公司做的项目需要实现导出Word文档的功能,网上关于POI生成Word文档的例子很少,找了半天才在官网里找到个Demo,有了Demo一切就好办了. /* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See

  • java中利用Dom4j解析和生成XML文档

    java中利用Dom4j解析和生成XML文档

    一.前言 dom4j是一套非常优秀的Java开源api,主要用于读写xml文档,具有性能优异.功能强大.和非常方便使用的特点.   另外xml经常用于数据交换的载体,像调用webservice传递的参数,以及数据做同步操作等等,   所以使用dom4j解析xml是非常有必要的. 二.准备条件 dom4j.jar 下载地址:http://sourceforge.net/projects/dom4j/ 三.使用Dom4j实战 1.解析xml文档 实现思路: <1>根据读取的xml路径,传递给SAX

  • python解析html提取数据，并生成word文档实例解析

    简介 今天试着用ptyhon做了一个抓取网页内容,并生成word文档的功能,功能很简单,做一下记录以备以后用到. 生成word用到了第三方组件python-docx,所以先进行第三方组件的安装.由于windows下安装的python默认不带setuptools这个模块,所以要先安装setuptools这个模块. 安装 1.在python官网上找到 https://bootstrap.pypa.io/ez_setup.py ,把代码保存到本地并执行: python ez_setup.py 2.下载

  • python实现的生成word文档功能示例

    本文实例讲述了python实现的生成word文档功能.分享给大家供大家参考,具体如下: 每月1次的测试费用报销,需要做一个文档.干脆花点时间写个程序吧. # -*- coding: utf-8 -*- from tools import get_data from docx import Document def new_doc(fee_data,doc_path,fee):#新建一个word文档,写入汇总表的数据 document = Document() p_total = document

  • Python文档生成工具pydoc使用介绍

    Python文档生成工具pydoc使用介绍

    在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc.doxygen.sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介绍pydoc. pydoc是Python自带的模块,主要用于从python模块中自动生成文档,这些文档可以基于文本呈现的.也可以生成WEB 页面的,还可以在服务器上以浏览器的方式呈现! [用法] Windows下: 复制代码 代码如下: D:\>python -m pydoc <modulenam

  • 使用Python 自动生成 Word 文档的教程

    当然要用第三方库啦 :) 使用以下命令安装: pip install python-docx 使用该库的基本步骤为: 1.建立一个文档对象(可自动使用默认模板建立,也可以使用已有文件). 2.设置文档的格式(默认字体.页面边距等). 3.在文档对象中加入段落文本.表格.图像等,并指定其样式. 4.保存文档. 注:本库仅支持生成Word2007以后版本的文档类型,即扩展名为.docx 的. 下面分步介绍其基本使用方法: 步骤一: from docx import Document doc = Do

  • 教你使用Python根据模板批量生成docx文档

    教你使用Python根据模板批量生成docx文档

    一.需求说明 能够根据模板批量生成docx文档.具体而言,读取excel中的数据,然后使用python批量生成docx文档. 二.实验准备 准备excel数据: 这里是关于学生语数英成绩的统计表,文件名为score.xls 准备模板: 这是给学生家长的成绩通知书,文件名为template.doc 另外,在使用python进行实验之前,需要先安装第三方库docxtpl和xlrd,直接pip install就行: pip install docxtpl pip install xlrd 然后将xls

  • golang组件swagger生成接口文档实践示例

    golang组件swagger生成接口文档实践示例

    目录 swagger介绍 gin-swagger实战 第一步:添加注释 第二步:生成接口文档数据 第三步:引入gin-swagger渲染文档数据 swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家

随机推荐