`sphinx`：基于 `Python` 的文档生成工具

Motivation

对于软件开发来说，文档是软件可维护性的重要保障。sphinx 是一款文档生成工具，以 restructuredText 为标记语言。更重点的是其 autodoc 插件支持从 Python docstring 生成文档，同一个模块、文件、类或者函数上进行说明，便于维护，并且非常 Pythonic。

顺便一提，sphinx 取名于埃及的狮身人面像斯芬克斯。

安装

基础包可以通过以下两种方式之一安装

pip install -U sphinx
conda install sphinx

安装完成后校验是否安装成功

 sphinx-build --version

优选地，安装 sphinx-reload 以实现监听文件变化并自动刷新 html 页面。

pip install sphinx-reload

使用

sphinx 软件包提供了一系列以 sphinx- 为前缀的命令行工具。对于项目初始化，我们需要使用 sphinx-quickstart。

首先切换到项目目录，然后

sphinx-quickstart docs

会提问几个问题，当前版本 5.0.2 主要问这几个问题：

Separate source and build directories（如果选 y，docs 下会有两个文件夹 source 和 build；如果选 n，docs 下是文档的根目录，编译后文件放在 _build 中。
Project name
Author name(s)
Project release
Project language（自然语言）

按实际情况回答即可。

配置

配置主要在 conf.py 中

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))project = 'Project'
copyright = '2023, Ruiming Guo'
author = 'Ruiming Guo'extensions = ["sphinx.ext.autodoc", # 重点，自动生成"sphinx.ext.doctest","sphinx.ext.coverage","sphinx.ext.viewcode",'sphinx.ext.mathjax',
]autodoc_default_options = {'members': True,'member-order': 'bysource','special-members': '__init__','undoc-members': True,'exclude-members': '__weakref__'
}templates_path = ['_templates']
exclude_patterns = []
html_theme = 'alabaster'
html_static_path = ['_static']
source_suffix = [".rst"]

运行

配置 autodoc 后，sphinx-reload 只会监听 docs/ 下的文件，如果要监听 python 文件中 docstring 的变化，需要

sphinx-reload . --watch ../**/*.py

编译

make html
make latex

sphinx：基于 Python 的文档生成工具相关推荐

python doc_Python文档生成工具pydoc使用介绍
在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc.doxygen.sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介 ...
关于深度学习框架Hamaa与Python API文档生成工具Sophon
五月两场 | NVIDIA DLI 深度学习入门课程 5月19日/5月26日一天密集式学习快速带你入门阅读全文> 正文共1988个字,预计阅读时间12分钟. 前言最近三个月我主要花时间在造 ...
python文档生成_python文档生成工具：pydoc、sphinx；django如何使用sphinx？
文档生成工具: 自带的pydoc,比较差建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...
java 接口文档工具_一款Java基于注释的接口文档生成工具
一. 痛点你还在手动维护接口文档嘛,花一个下午不停的复制粘贴代码里面的注释接口字段变动,还得去更新文档,更新不及时导致文档不同步或者你使用了swagger之类的基于注解,依靠运行时的文档工具,看 ...
基于文档注释接口文档生成工具(代码0侵入附源码)
本文主要分享一个基于个人兴趣,旨在提高工作效率,开发了一个基于文档注释,接口文档生成工具,欢迎大佬指点. 源码以及使用demo地址 :传送门 1.前置介绍 1.1前世现在大多数项目都走向了前后端分离 ...
mysql 文档生成器_最好用的数据库文档生成工具
一前言本文介绍一些比较流行的数据库文档生成工具,什么是数据库文档? 其实在工作中进行项目交付的时候经常用到:简单来说数据库文档就是对整个数据库设计说明的文档,比如使用了哪个数据库,每张表的字段,类 ...
Apiggs —— 非侵入性的 RestDoc 文档生成工具
程序员一直以来都有一个烦恼,只想写代码,不想写文档.代码就表达了我的思想和灵魂. Python提出了一个方案,叫docstring,来试图解决这个问题.即编写代码,同时也能写出文档,保持代码和文档的一 ...
.NET平台开源项目速览(4).NET文档生成工具ADB及使用
.NET平台开源项目速览(4).NET文档生成工具ADB及使用原文:.NET平台开源项目速览(4).NET文档生成工具ADB及使用很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习 ...
Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...

sphinx：基于 Python 的文档生成工具

`sphinx`：基于 `Python` 的文档生成工具

Motivation

安装

使用

配置

运行

编译

sphinx：基于 Python 的文档生成工具相关推荐

最新文章

热门文章