Python文档管理与格式化工具
作者:互联网
目录
1. 代码格式化
1.1. autopep8
pip install autopep8
简单使用:
autopep8 -aa <filename>
-
-aa
表示代码侵入性级别。这里解释一下侵入性aggressive。-
当不使用
--aggressive
选项时,autopep8
只会对空格进行格式化 ,不会修改你的其他语法。 -
当使用1个--aggressive时,表示侵入性级别1,会修改一些不推荐的语法。比如
x == None
会被修改为x is None
。但这有一定的风险,可能会改变原来程序的语义,比如例子中,x如果改写了__eq__
方法,就会有问题。 -
当使用2个--aggressive时,侵入性级别增加1,
if x == True:
之类的代码会被改为if x:
。
个人建议,在自己的编辑器中使用flake8(也使用了pycodestyle)等插件进行提示即可,不要依赖于autopep8来修改源码。
-
-
--max-line-length=n
可以设置每行代码的最长字符限制,默认是79。社区中很多人反映79个字符的长度限制应该放宽,毕竟这是历史原因导致的。
-
--in-place
(缩写-i)不再输入格式化后的代码,而是将格式化直接应用到源文件上,改写源文件。
1.2. YAPF
个人推荐使用 yapf
来取代 autopep8
。
不同于autopep8、pep8ify之类的Python代码格式化程序: 它们的目的是消除Python代码中不符合PEP-8规范的错误。符合规范的代码不会被修改。然而,符合PEP-8规范的代码,不一定是好看的代码。
yapf使用clang-format算法来实现代码的重新排版,即便代码本来就符合规范。
pip install yapf
安装后,你可以试着使用 yapf <filename>
来格式化前面例子中的丑陋代码。
1.3. docformatter
pip install --upgrade docformatter
简单使用: docformatter --in-place example.py
2. 文档API生成工具
2.1. pdoc(注意,不是pydoc)
pdoc 是一个简单易用的命令行工具,可以生成 Python 的 API 文档。
2.2. Sphinx
Python有个自带的工具可以生成API项目文档——pydoc,但Python3官方文档却是由sphinx生成的。可见Sphinx已成为Python项目首选的文档工具,同时它对C/C++项目也有很好的支持。
Sphinx 运行前需要安装 docutils 和 Jinja2 & requests 库. Sphinx 必须工作在 0.7 版本及一些 SVN 快照(不能损坏). 如果需要源码支持高亮显示,则必须安装 Pygments 库.
# pip install requests jinja2 docutils
pip install sphinx
这一节搜集了一些有用的提示,帮助我们从其他的文档系统迁移到reStructuredText/Sphinx.
- Gerard Flanagan (人名)写了一个脚本把纯净的HTML转换为 reST 文本;
- 原来的Python文档转换为 Sphinx, 代码托管在 the Python SVN repository. 它包含将Python-doc-style LaTeX 标记转换为 Sphinx reST 的生成代码.
- Marcin Wojdyr 写了一个脚本,将 Docbook 转换为 reST ; 可查看 Google Code.
- Christophe de Vienne 写了一个将 Open/LibreOffice 文档转换为 Sphinx的工具: odt2sphinx.
- 转换不同的标记语言, Pandoc 也是一个非常有用的工具.
cd xxx/src # 进入项目目录
mkdir docs && cd docs
sphinx-quickstart
# 注意 autodoc 的地方一定要选是,其他选默认没什么问题。
# 最后直接生成html
make html
2.2.1. 支持C++文档(对比Doxygen)
Doxygen已经存在了几十年,是一种稳定的,功能丰富的工具,用于生成文档。但是,这并非没有问题。用Doxygen生成的文档往往在视觉上比较嘈杂,具有90年代初期的风格,并且难以清晰地表示基于模板的复杂API。其标记也有局限性。尽管他们在2012年增加了对Markdown的支持,但Markdown并不是编写技术文档的最佳工具,因为它为简化而牺牲了可扩展性,功能集大小和语义标记。
Sphinx改为使用 reStructuredText
,它具有Markdown缺少的那些重要概念作为核心理想。可以将自己的“角色”和“指令”添加到标记中,以进行特定于域的自定义。
与Doxygen相比,Sphinx生成的文档看上去也更现代,更精简,并且可以更轻松地交换不同的主题,自定义显示的信息量以及修改页面的布局。
-
安装环境
sudo apt install doxygen # 安装Doxygen,用于从C++头文件提取API # pip install sphinx_rtd_theme # 可选,安装主题 pip install breathe # 利用Doxygen从C++提取文档 sudo apt install cmake
-
创建编译文件:
- CatCutifier/CMakeLists.txt
cmake_minimum_required (VERSION 3.8) project ("CatCutifier") add_subdirectory ("CatCutifier")
- CatCutifier/CatCutifier/CMakeLists.txt
add_library (CatCutifier "CatCutifier.cpp" "CatCutifier.h") target_include_directories (CatCutifier PUBLIC .)
-
头文件的格式(同Doxygen)
CatCutifier/CatCutifier/CatCutifier.h #pragma once /** A fluffy feline */ struct cat { /** Make this cat look super cute */ void make_cute(); };
-
配置Doxygen
> mkdir docs > cd docs > doxygen.exe -g
We can get something generated quickly by finding the INPUT variable in the generated Doxyfile and pointing it at our code:
INPUT = ../CatCutifier
。 -
执行编译和文档生成
> doxygen.exe
标签:Sphinx,Python,代码,CatCutifier,文档,install,格式化 来源: https://www.cnblogs.com/brt2/p/13232420.html