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

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
    
上一篇:使用 sphinx 制作简洁而又美观的文档


下一篇:开源的语音交互平台简介及对比