首页 > 其他分享 >使用sphinx生成项目文档

使用sphinx生成项目文档

时间:2023-07-06 13:12:10浏览次数:46  
标签:sphinx docs 生成 source theme html 文档

Sphinx是一个基于Python的文档生成工具,它可以将标记文本转换为各种格式的文档,包括HTML、PDF、EPUB等。Sphinx最初是为Python文档而开发的,但是它也可以用于其他类型的文档,例如API文档、技术文档、用户手册等。

Sphinx的主要特点包括:

  • 支持多种标记语言,包括reStructuredText、Markdown等。
  • 支持多种输出格式,包括HTML、PDF、EPUB等。
  • 支持自定义主题和样式,可以根据需要进行定制。
  • 支持自动生成API文档和代码示例。
  • 支持自动生成索引、目录、交叉引用等。

Sphinx的使用方法比较简单,通常包括以下步骤:

  1. 安装Sphinx
    可以使用pip命令安装Sphinx:
pip install sphinx
  1. 初始化项目
    使用sphinx-quickstart命令初始化Sphinx项目,该命令会生成一个包含配置文件和目录结构的项目(建议在项目中新建一个docs目录,在docs目录下执行该命令):
mkdir docs && cd docs
sphinx-quickstart

按照提示输入相关信息

Welcome to the Sphinx 7.0.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: . 

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y  # 是否分离文档源码和生成的HTML

The project name will occur in several places in the built documentation.
> Project name: python-yapi    # 项目名称
> Author name(s): Han Zhichao  # 作者名称
> Project release []: 0.1.0   # 项目版本

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: en   #  语言

Creating file /Users/superhin/Projects/python-yapi/docs/source/conf.py.
Creating file /Users/superhin/Projects/python-yapi/docs/source/index.rst.
Creating file /Users/superhin/Projects/python-yapi/docs/Makefile.
Creating file /Users/superhin/Projects/python-yapi/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/superhin/Projects/试验/argparse_demo/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

运行后在docs目录下生成source(文档源码)和build(用于生成HTML文档)目录和Makefile相关文件(用于支持make html命令)。
source中包含了sphinx的配置文件conf.py以及文档首页index.rst
效果如下图:

image

  1. 编写文档
    在source目录下编写文档,可以使用reStructuredText或Markdown等标记语言。

reStructuredText格式参考:https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/basics.html

  1. 生成文档
    使用make命令生成文档,例如:
make html

该命令会生成HTML格式的文档,保存在build/html目录下。

Sphinx还提供了丰富的配置选项和插件,可以根据需要进行定制。你可以参考Sphinx官方文档,了解更多详细信息和用法示例。

生成模块文档

使用sphinx-apidoc命令可以根据Python模块注释自动生成模块文档。

  1. 修改sphinx配置conf.py,在模块查找路径中添加当前项目根路径。
    在conf.py文件头部添加
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # 将项目根目录添加到模块查找路径中去

在 conf.py扩展配置中添加 'sphinx.ext.autodoc',和 'sphinx.ext.viewcode',

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
]
  • sphinx.ext.autodoc:根据代码注释自动生成模块文档。
  • sphinx.ext.viewcode:增加[source]查看源码功能。
  1. 在命令行进入docs/目录,使用sphinx-apidoc命令生成python_yapi模块文档到source目录
cd docs
sphinx-apidoc -o source ../python_yapi

执行后在source目录下生成modules.rst和python_yapi.rst, 如下图:
image

在index.rst内容列表中添加modules
image

在docs目录,命令行使用make html生成文档,使用浏览器打开build/html目录的index.html

image

使用 readthedoc 主题

原生主题白且单调,可以安装使用sphinx_rtd_theme

  1. 安装主题
pip install sphinx-rtd-theme
  1. 使用主题
    修改sphinx配置conf.py,导入sphinx_rtd_theme,并修改html_theme及html_theme_path配置
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
  1. 重新make html生成文档
    浏览器打开build/html/index.html,效果如下:

image

文档托管-发布文档到Readthedocs

  1. 在项目根目录下新建文件.readthedocs.yaml,指定sphinx配置文件路径,并上传代码到GitHub仓库。
version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.9"
sphinx:
   configuration: docs/source/conf.py  # sphinx配置文件路径
  1. 打开https://readthedocs.org/ ,使用Github登录(或注册登录)
    导入当前项目(或手动导入项目)

image

点击Build version按钮,成功后点击阅读文档即可查看发布后的文档。

image
23.cnblogs.com/blog/1064540/202307/1064540-20230706121932687-1626144614.png)

多语言文档(文档翻译)

  1. 在readthedocs上想要生成支持多语言文档,需要另外新建一个Github项目,如
    python-yapi-docs-zh_CN,
  2. 拷贝上一个项目docs及.readthedocs.yaml到当前项目

image

  1. 安装sphinx、sphinx-rtd-theme和多语言翻译工具sphinx_intl
pip install sphinx sphinx-rtd-theme sphinx_intl
  1. 在sphinx配置conf.py中添加语言及国际化目录配置
language = 'zh_CN'
locale_dirs = ['locale/']
  1. 提取文本及生成待翻译(中文)文本
cd docs/source
sphinx-build -b gettext . locale
sphinx-intl update -p locale -l zh_CN
cd ..
  1. 手动翻译docs/source/locale/zh_CN/LC_MESSAGES中所有的.po文件,其中msgid是原始英文,msgstr是要翻译的对应的中文,如下图:

image

注意:不翻译locale目录下的.po文件。

  1. 在docs目录下使用make html并查看build/html/index.html
    效果如下:

image

  1. 上传到Github并在readthedocs中导入项目,并设置其语言为Simplified Chinese,如下图:

image

  1. 在主项目中添加翻译和子项目

image

image

查看文档,将url中的en修改为zh_CN后即可查看中文文档,如下图:

image

参考:readthedocs(RTD)托管持多语言文档

标签:sphinx,docs,生成,source,theme,html,文档
From: https://www.cnblogs.com/superhin/p/sphinx-apidoc.html

相关文章

  • 使用html2canvas生成网页截图并下载
    1.安装依赖npminstallhtml2canvas--save2.引入依赖importhtml2canvasfrom"html2canvas";3.使用示例<template><div><a@click="toImage()">下载</a><divref="imageTofile"> 要截屏的控件内容</div>&......
  • Jira最新安装破解文档,企业常用项目管理工具Jira
    jira安装具体步骤安装docker启动docker上传并解压(tar-xvf)数据库驱动(tar.gz),上传破解jar包(atlassian-agent.jar)运行命令,下载镜像并启动mysql容器dockerrun--namemysql--restartalways-p3306:3306-eMYSQL_ROOT_PASSWORD=wjj123456......
  • aconvert 一个支持多 音视频、多文档格式、压缩包格式转换在线网站
    一个支持多音视频、多文档格式、压缩包格式转换在线网站地址web截图......
  • PowerShell系列九:文档和测试
    文档functionAdd-Access{<#.SYNOPSIS文件和目录添加访问权限.DESCRIPTIONIcacls的包装,能够对目录和文件添加三种权限。读取,修改,完全控制.PARAMETERPath需要添加权限的{文件|目录}.PARAMETERUser授予访问......
  • word文档的图片怎么保存到百度ueditor上
    ​ 当前功能基于PHP,其它语言流程大致相同 1.新增上传wordjson配置在ueditor\php\config.json中新增如下配置:     /* 上传word配置 */    "wordActionName":"wordupload",/* 执行上传视频的action名称 */    "wordFieldName":"upfile",/* 提交的......
  • word文档的图片怎么保存到百度编辑器上
    ​ 1.编辑器修改(可选)1.1在 ueditor/config.json 中添加代码块    /* 上传word配置 */    "wordActionName":"wordupload",/* 执行上传视频的action名称 */    "wordFieldName":"upfile",/* 提交的视频表单名称 */    "wordPathFormat":"/p......
  • word文档的图片怎么保存到百度Web编辑器上
    ​ 图片的复制无非有两种方法,一种是图片直接上传到服务器,另外一种转换成二进制流的base64码目前限chrome浏览器使用首先以um-editor的二进制流保存为例:打开umeditor.js,找到UM.plugins['autoupload'],然后找到autoUploadHandler方法,注释掉其中的代码。加入下面的代码://判断剪......
  • Linux随机生成数
    简介在某些情况下,我们需要随机产生一个数来在一些场景中使用,例如验证码、ssh反向代理随机数的产生,又或者在一些shell脚本设计中需要用到随机数,这里介绍常用几个linux产生随机数的方法。使用shufshuf命令在一些Linux系统中是自带的,但并不是所有系统都包含该命令。在Ubuntu......
  • Mybatis-generator插件快速生成代码
    生成步骤:在pom.xml中添加插件<!--mybatisGenerator插件--><plugin><groupId>org.mybatis.generator</groupId><artifactId>mybatis-generator-maven-plugin</artifactId><version>1.4.0</version><depende......
  • 向AI请教能否用图片生成vue代码
    Canfigmageneratevuecodebasedonascreenshotcapturedfromanandroidapp?Wed,Jul5,2023,3:49pmavatarNo,FigmadoesnotnativelygenerateVuecodebasedonascreenshotcapturedfromanAndroidapp.Figmaisprimarilyadesignandprototyping......