Question

我如何让Asciidoc（tor）生成例如。一个很好的总体功能描述，其中包含几个代码注释和一些代码（包括函数签名），而没有用标记屠杀我的代码？

AFAIK Asciidoc仅通过以下代码中的周围标签在其Asciidoc文件中支持外部包含

# tag::mytag[] 
<CODE TO INCLUDE HERE>
# end::mytag[]

在单个函数体内的每个描述性注释以及每个函数签名周围都会非常嘈杂。也许有一种奇特的，不太冗长的方式，例如标记诸如#!之类的单行注释和单行标签，该标签告诉Asciidoctor仅读取相对于这些标签的一行。

考虑这个小例子。

def uber_func(to_uber: str) -> str:
    """
    This is an overall description. Delivers some context.
    """

    # Trivial code here

    # To uber means <include code below>
    result = to_uber + " IS SOOO " + to_uber + "!!!"

    # Trivial code here

    # Function only returns upper case.
    return result.upper()

我朴素的Asciidoc方法包含所有有意义的注释，上面代码中的docstring和函数签名看起来很糟糕，再加上Asciidoc无法识别和删除注释标记，因此生成的文档可能也不太漂亮。

而不是这很丑

# tag::uber_func[]
def uber_func(to_uber: str) -> str:
    """
    This is an overall description. Delivers some context.
    """
# end::uber_func[]

    # Trivial code here

    # tag::uber_func[]
    # To uber means
    result = to_uber + " IS SOOO " + to_uber + "!!!"
    # end::uber_func[]

    # Trivial code here

    # tag::uber_func[]
    # Function only returns upper case.
    # end::uber_func[]
    return result.upper()

我想使用类似（pseudo）的东西：

def uber_func(to_uber: str) -> str:
    # tag::uber_func[readline:-1,ignore-comment-marks,doc-comment:#!]
    #! This is an overall description. Delivers some context.

    # Trivial code here

    #! To uber means
    # tag::uber_func[readline:+1]
    result = to_uber + " IS SOOO " + to_uber + "!!!"

    # Trivial code here

    #! Function only returns upper case.
    return result.upper()
    # end::uber_func[]

我认为通常的问题是， Asciidoc仅仅是文本格式化工具，这意味着，如果我希望它主要从我的代码生成结构化文档，则我需要提供此结构在我的代码和.adoc文件中。另一侧的文档生成器（例如Doxygen）会自动识别该结构以及文档注释。我非常重视此功能，有些生成器允许您并排编写代码和漂亮的文档，从而大大降低了整体工作量。如果Asciidoc不允许我以合理的方式进行此操作，那么我将寻找其他东西。

Answer 1

我认为您必须编写一个刮板，将注释放入一个结构中，然后将该结构放入您的AsciiDoc中。这样，注释可以使用AsciiDoc标记在内部进行格式化，并且可以将其输出到Asciidoctor生成的文档中，但是您不需要Asciidoctor即可直接读取源文件。

我会尝试一种系统，该系统使用一个#来发布未发表的评论，使用##来代表您要发布的评论，反之亦然，或者追加一个{{ 1}}用于文档发布。以及用#表示法表示的那些。然后，您的抓取工具可以读取块名称（"""或重要的任何部分），然后抓取管理者注释和所有文字代码，并将它们全部排列在文件中。以下文件中，大多数注释标记为uber_func，非管理员注释被删除，非注释内容为text：

code

我知道这看起来很可怕，但是对于AsciiDoc模板来说超级有用。例如，仅使用：

# tag::function__uber_func[]
# tag::function__uber_func_form[]
uber_func(to_uber: str) -> str:
# end::function__uber_func_form[]
# tag::function__uber_func_desc[]
This is an overall description. Delivers some context.
# end::function__uber_func_desc[]
# tag::function__uber_func_body[]
# tag::function__uber_func_text[]
To uber means
# end::function__uber_func_text[]
# tag::function__uber_func_code[]
----
result = to_uber + " IS SOOO " + to_uber + "!!!"
----
# end::function__uber_func_code[]
# tag::function__uber_func_text[]
Function only returns upper case.
# end::function__uber_func_text[]
# tag::function__uber_func_code[]
----
return result.upper()
----
# end::function__uber_func_code[]
# end::function__uber_func[]

如果将其解析为数据格式（例如JSON或YAML），然后将其动态压入AsciiDoc模板，则效果会更好。但是，如果它不太庞大，则可以保持上面类似的内容。在一定大小（20多个这样的记录？）上，您需要一个中间数据源（由抓取生成的临时数据文件），在更大的规模（> 100个代码块/端点？）上，您可能需要一个专门的系统在API文档中，例如Doxygen等。

根据注释代码生成结构化文档

1 个答案: