Mat*_*ieu 6 python documentation
我将编写一组脚本，每个脚本独立于其他脚本，但有一些相似之处。所有脚本的结构很可能都相同，可能看起来像：
# -*- coding: utf-8 -*-
"""
Small description and information
@author: Author
"""
# Imports
import numpy as np
import math
from scipy import signal
...
# Constant definition (always with variable in capital letters)
CONSTANT_1 = 5
CONSTANT_2 = 10
# Main class
class Test():
def __init__(self, run_id, parameters):
# Some stuff not too important
def _run(self, parameters):
# Main program returning a result object.
对于每个脚本，我想编写文档并将其导出为 PDF。我需要一个库/模块/解析器来读取脚本、提取注释、代码并将其重新组合成所需的输出格式。
例如，在_run()方法中，注释中可能有几个详细的步骤：
def _run(self, parameters):
# Step 1: we start by doing this
code to do it
# Step 2: then we do this
code to do it
code
code # this code does that
我可以使用哪个库/解析器来分析 python 脚本并输出 PDF？ 起初，我在考虑sphinx，但它不适合我的需要，因为我必须设计一个自定义扩展。此外，sphinx 的优势在于相同或不同模块的多个脚本之间的链接和层次结构。就我而言，我一次只会记录一个脚本，一个文件。
然后，我的第二个想法是使用RST格式和RST2PDF来创建 PDF。对于解析器，我可以设计一个解析器，它读取.py文件并提取下面建议的注释/装饰行或行集，然后编写RST文件。
#-description
## Title of something
# doing this here
#-
#-code
some code to extract and put in the doc
some more code
#-
最后，我还希望能够执行一些代码并捕获结果，以便将其放入输出 PDF 文件中。例如，我可以运行 python 代码来计算.py文件内容的 SHA1 哈希值，并将其作为参考包含在 PDF 文档中。
为了让事情变得更容易，您可能想使用文档字符串而不是注释：
\n\n\n文档字符串是一个字符串文字，作为模块、函数、类或方法定义中的第一个语句出现。这样的文档字符串成为
\n__doc__该对象的特殊属性。
__doc__这样，您可以在生成文档时解析脚本时使用该属性。
紧接在成为文档字符串的函数/模块定义之后放置的三个双引号字符串只是语法糖。您可以__doc__根据需要以编程方式编辑属性。
例如，您可以使用装饰器来使文档字符串的创建在您的特定情况下更好。例如，让您内联注释步骤，但仍将注释添加到文档字符串中（在浏览器中编程，可能有错误）：
\ndef with_steps(func):\n def add_step(n, doc):\n func.__doc__ = func.__doc__ + "\\nStep %d: %s" % (n, doc)\n func.add_step = add_step\n\n@with_steps\ndef _run(self, parameters):\n """Initial description that is turned into the initial docstring"""\n _run.add_step(1, "we start by doing this")\n code to do it\n \n _run.add_step(2, "then we do this")\n code to do it\n code \n这将创建一个像这样的文档字符串：
\n\n\n转换为初始文档字符串的初始描述
\n
\n第 1 步：我们首先执行此操作
\n第 2 步：然后我们执行此操作
你明白了。
\n就我个人而言，我只是尝试使用 Sphinx 可用的 PDF 构建器，通过捆绑的LaTeXBuilder或使用rinoh（如果您不想依赖 LaTeX）。
\n但是，您必须使用 Sphinx 理解的文档字符串格式，例如 reStructuredText 或 Google Style Docstrings。
\n AST \n另一种方法是使用ast来提取文档字符串。这可能是 Sphinx autodoc 扩展在内部使用的从源文件中提取文档的方法。有一些关于如何执行此操作的示例，例如此要点或此博客文章。
\n这样您就可以编写一个脚本来解析并输出您想要的任何格式。例如，您可以输出 Markdown 或 reST 并使用pandoc将其转换为 PDF 。
\n您可以直接在文档字符串中编写标记文本，这将为您提供很大的灵活性。假设您想使用 markdown \xe2\x80\x93 编写文档，只需直接在文档字符串中编写 markdown 即可。
\ndef _run(self, parameters):\n """Example script\n ================\n\n This script does a, b, c\n\n 1. Does something first\n 2. Does something else next\n 3. Returns something else\n\n Usage example:\n \n result = script(parameters)\n foo = [r.foo for r in results]\n """\n可以使用 ast 提取该字符串，并使用您认为合适的任何库进行解析/处理。
\n| 归档时间： |
|
| 查看次数： |
388 次 |
| 最近记录： |