Python文档管理与格式化工具

Posted 2020-12-14 brt2

目录

• 1. 代码格式化
  • 1.1. autopep8
  • 1.2. YAPF
  • 1.3. docformatter
• 2. 文档API生成工具
  • 2.1. pdoc（注意，不是pydoc）
  • 2.2. Sphinx
    • 2.2.1. 支持C++文档（对比Doxygen）

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

github

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生成的文档看上去也更现代，更精简，并且可以更轻松地交换不同的主题，自定义显示的信息量以及修改页面的布局。

1. 安装环境

   sudo apt install doxygen  # 安装Doxygen，用于从C++头文件提取API
   # pip install sphinx_rtd_theme  # 可选，安装主题
   pip install breathe  # 利用Doxygen从C++提取文档
   sudo apt install cmake
   

2. 创建编译文件：

   • 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 .)
   

3. 头文件的格式（同Doxygen）

   CatCutifier/CatCutifier/CatCutifier.h
   #pragma once
   
   /**
     A fluffy feline
   */
   struct cat {
       /**
       Make this cat look super cute
       */
       void make_cute();
   };
   

4. 配置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 。

5. 执行编译和文档生成

   > doxygen.exe