中国空间站有多大,镇江网站建设优化案例分析,成都网络推广网站,成都网站建设公司盈利吗1、简介
Sphinx是Python文档生成器#xff0c;它基于reStructuredText标记语言#xff0c;可自动根据项目生成HTML#xff0c;PDF等格式的文档#xff0c;无数著名项目的文档均用Sphinx生成#xff0c;如机器学习库scikit-learn、交互式神器Jupyter Notebook
sphinx是一…1、简介
Sphinx是Python文档生成器它基于reStructuredText标记语言可自动根据项目生成HTMLPDF等格式的文档无数著名项目的文档均用Sphinx生成如机器学习库scikit-learn、交互式神器Jupyter Notebook
sphinx是一种基于Python的文档工具它可以令人轻松的撰写出清晰且优美的文档由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的并且它已成为Python项目首选的文档工具同时它对C/C项目也有很好的支持。更多详细特性请参考spinx官方文档本篇博客主要介绍如何快速为你的Python注释生成API文档。
2、安装sphinx
pip install sphinx3、生成api
新建项目sphinx_demosrc放项目代码doc放sphinx自动生成的文件
2.命令行进入doc目录cd doc 3.执行命令sphinx-quickstart设置结构分离、项目名、作者名、版本号、语言配置后面可修改 Separate source and build directories (y/n) [n]: y Project name: sphinx_demo Author name(s): XerCis Project release []: 1.0 Project language [en]: zh_CN 或 回车默认英文 4.在doc/source/conf.py指定项目代码路径
import os
import sys
sys.path.insert(0, os.path.abspath(../../src))5.在doc/source/conf.py修改扩展extensions添加功能【包括注释中的文档】、【支持NumPy和Google风格】、【包括测试片段】、【链接到其他项目的文档】、【TODO项】、【文档覆盖率统计】、【通过javascript呈现数学】
extensions [sphinx.ext.autodoc,sphinx.ext.napoleon,sphinx.ext.doctest,sphinx.ext.intersphinx,sphinx.ext.todo,sphinx.ext.coverage,sphinx.ext.mathjax,
]在source/index.rst下新增如下内容
.. toctree:::maxdepth: 2:caption: Contents:7.命令行进入doc目录执行生成API文档命令sphinx-apidoc -o source …/src/ 8.生成HTML (linux环境执行命令)
make html windows环境需要执行命令
.\make html4、重新生成
项目代码未变更
1 . 在doc下执行命令 make clean 2. 在doc下执行命令 make html直接也行 项目代码已变更 删除 doc/build 下的所有文件夹 删除 doc/source 下除index.rst的所有.rst文件 在doc下执行命令 sphinx-apidoc -o source …/src/ 在doc下执行命令 make html
切换主题
安装主题 pip install sphinx_rtd_theme 修改 doc/source/conf.py 的 html_theme
html_theme ‘sphinx_rtd_theme’ 注释风格 reStructuredTextPyCharm默认 NumPy Google官方推荐
风格 特点 适用 reStructuredText 用冒号分隔 PyCharm默认 NumPy 用下划线分隔 倾向垂直长而深的文档 Google 用缩进分隔 倾向水平短而简单的文档 Sphinx对NumPy和Google风格的对比英文不好可以参考中文版
extensions [‘sphinx.ext.napoleon’]
设置PyCharm Docstrings风格 File→Settings→Tools→Python Integrated Tools
在PyCharm中CtrlQ可很方便查看注释
光标放在函数名左端AltEnter→Insert documentation string stub可快速插入注释文档
项目结构
docSphinx文件 src项目源代码 doc/buildSphinx生成文件 doc/build/doctreesdoctree文件 doc/build/html生成的HTML文件 doc/sourceSphinx配置文件 doc/source/conf.pySphinx用户自定义配置文件 doc/source/index.rst首页结构 doc/source/test.rsttest模块结构 主题大全 Sphinx的主题默认为 alabaster
参考文档 https://blog.csdn.net/lixiaomei0623/article/details/120530642 https://www.cnblogs.com/Terrypython/p/10203332.html
