python文档管理工具程序_Python文档管理与格式化工具

目录

1. 代码格式化

1.1. autopep8

pip install autopep8

简单使用：

autopep8 -aa

-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 来格式化前面例子中的丑陋代码。

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