建设网站 注册与登陆,1000元能否做网站,软件app免费下载,免费申请信用卡一、参考资料
从Python源码注释#xff0c;自动生成API文档
二、问题引入
不管是开源还是闭源#xff0c;要让所有人都能读懂你的代码这太难了#xff0c;所以文档是很重要的。大部分情况#xff0c;我们不希望维护一份代码再加上一份文档#xff0c;这样做很容易造成文…一、参考资料
从Python源码注释自动生成API文档
二、问题引入
不管是开源还是闭源要让所有人都能读懂你的代码这太难了所以文档是很重要的。大部分情况我们不希望维护一份代码再加上一份文档这样做很容易造成文档和代码的不一致程序员最讨厌更新文档了。
为了尽量减少工作量API调用部分最好能直接用源码注释生成——这样至少不用写两遍了而且注释离源码最近相互对照写起来方便。
三、Pydocs
python环境自带但是有点过于简单只能一个个指定文件/类/模块来生成文档生成的内容缺省输出到控制台还得重定向到文件优势是原生支持Markdown。
四、Sphinx
使用 Sphinx 为项目自动生成 API 文档
How-To Guides
Sphinx 使用手册 Learn reStructureText
RST 中文文档 v2.0.2
Sphinx doc官网
老牌文档生成工具和MkDocs一样都是完整的文档组织管理工具可以生成Html文档全套文档要当做一个项目来管理。如果要从源码注释生成文档需要安装autodoc等扩展。Sphinx最大的缺点在于要使用一种叫做**reStructuredText.rst文件**的文档格式很别扭。
1. RST
reStructuredText (RST、ReST或reST)一种用于文本数据的文件格式基于 Python 的 docutils 模块提供解析功能的标记语言。
2. 常用指令
# 查看Sphinx版本
sphinx-build --version3. 关键步骤
3.1 安装Sphinx
pip install sphinx
sudo apt install python3-sphinx3.2 设置文档源目录
在同一个项目中维护代码和文档需要在项目根目录新建一个 docs 文件夹也可以使用其他名称用来存放所有和文档有关的文件我们将使用该文件夹作为 Sphinx 工作的源目录source directory。
mkdir docs
cd docs# 初始化文档项目
sphinx-quickstartdocs
├── build # 存放生成的文档
│ ├── doctrees
│ └── html
├── make.bat
├── Makefile
└── source # 存放Sphinx工程源码├── api_python├── conf.py├── index.rst├── _static└── _templates解释说明
conf.py 配置文件整个项目的配置文件可以配置插件、主题、项目名称、中英文等。Makefile 和 make.bat 编译所需脚本在 docs 目录执行 make html 即可通过源文件生成静态网页。index.rst 是文档源文件的首页文档里有一些默认的样板内容通常我们将其作为访问其他页面的入口目录。build 文件夹下存放的是编译后产生的文件
3.3 生成文档
运行 make html 生成静态网页用于预览生成的 HTML 页面保存在 build/html 目录。
make html4. Markdown支持
python sphinx(文档生成器)入门
4.1 安装markdown支撑的模块
pip install myst-parser4.2 安装md文档相关主题
pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables4.3 设置插件
在conf.py文件中设置extensions字段添加md文档处理。
extensions [recommonmark]4.4 新建md文件
下面在source文件夹下新建一个子文件夹叫test, 里面存放md文档相关数据此处新建一个test.md文档内容如下:
## 简介
## 测试图片
4.5 在主目录中添加md文件目录
在 index.rst中修改如下
.. toctree:::maxdepth: 2test/test5. 编译
在项目根目录下执行如下命令转为html
# 需要注意windows是bat文件
make html注意事项 关于图片的引用sphinx会自动将图片文件移动到_images文件夹下不同文件夹下的图片都会移动到这个文件夹下图片名称不建议使用中文名称会导致无法正常移动图片。 关于图片不同文件夹下名称相同移动后会将同名的文件进行重命名添加序号之类的因此不会影响实际显示效果。 关于部分md文档中标题无法在目录中正常显示问题需要在conf.py文件中添加如下配置 html_theme_options {collapse_navigation: True, navigation_depth: 6}6. 应用案例
MindSpore的教程和API文档均可由Sphinx工具生成。
五、MkDocs
MkDocs是相对新的文档管理工具通过Markdown格式来组织文档安装插件Mkdocstrings以后也支持从源码注释生成md文件。
六、Doxygen
参考资料
干货|教你使用Doxygen制作漂亮的程序文档
Doxygen文档生成工具教程
文档生成神器—doxygen的使用和代码注释规范
自定义Doxygen生成小而美的文档
