python - 根据里面的评论记录和详细说明单个脚本

Question

我将编写一组脚本，每个脚本都独立于其他脚本，但有一些相似之处。所有脚本的结构很可能是相同的，可能看起来像:

# -*- 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 文档中。

Answer 1

文档字符串而不是注释
为了让自己更轻松，您可能希望使用 docstrings而不是评论:

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

这样，您可以使用 __doc__生成文档时解析脚本时的属性。
紧跟在成为文档字符串的函数/模块定义之后的三个双引号字符串只是语法糖化。您可以编辑 __doc__根据需要以编程方式设置属性。
例如，您可以使用 decorators在您的特定情况下更好地创建文档字符串。例如，让您在内联注释步骤，但仍将注释添加到文档字符串(在浏览器中编程，可能有错误):

def with_steps(func):
  def add_step(n, doc):
    func.__doc__ = func.__doc__ + "\nStep %d: %s" % (n, doc)
  func.add_step = add_step

@with_steps
def _run(self, parameters):
  """Initial description that is turned into the initial docstring"""
  _run.add_step(1, "we start by doing this")
  code to do it
        
  _run.add_step(2, "then we do this")
  code to do it
  code 

这将创建一个这样的文档字符串:

Initial description that is turned into the initial docstring
Step 1: we start by doing this
Step 2: then we do this

你明白了。
从记录的脚本生成 PDF
狮身人面像
就个人而言，我只是通过捆绑的 LaTeXBuilder 尝试可用于 Sphinx 的 PDF 构建器。或使用 rinoh如果你不想依赖 LaTeX。
但是，您必须使用 Sphinx 能够理解的文档字符串格式，例如 reStructuredText 或 Google Style Docstrings。
AST
另一种方法是使用 ast提取文档字符串。这可能是 Sphinx 自动文档扩展在内部用于从源文件中提取文档的内容。有一些关于如何执行此操作的示例，例如 this gist或 this blog post .
通过这种方式，您可以编写一个脚本来解析和输出您想要的任何格式。例如，您可以输出 Markdown 或 reST 并使用 pandoc 将其转换为 PDF。 .
您可以直接在文档字符串中编写标记的文本，这会给您很大的灵 active 。假设您想使用 markdown 编写文档 - 只需直接在您的文档字符串中编写 markdown。

def _run(self, parameters):
  """Example script
  ================

  This script does a, b, c

  1. Does something first
  2. Does something else next
  3. Returns something else

  Usage example:
  
      result = script(parameters)
      foo = [r.foo for r in results]
  """

可以使用 ast 提取此字符串，并使用您认为合适的任何库进行解析/处理。