0

How do i get Asciidoc(tor) to generate eg. a nice overall function description out of several code comments and some code, including the function signature, without butchering my code with tags?

AFAIK Asciidoc only supports external includes in its Asciidoc file via surrounding tags in the code like

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

which would be quite noisy around every describing comment within a single function body and around every function signature. Maybe there is an exotic, less verbose way like marking the single line comments like #! and single line tags that tells Asciidoctor to read only a single line relative to these tags.

Consider this tiny example.

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()

My naive Asciidoc approach to include all meaningfull comments, the docstring and the function signature from the code above would look awefull, plus, Asciidoc doesn't recognize and remove comment marks, so the resulting documentation might not be so pretty too.

Instead of this very ugly

# 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()

I would like to use some thing like (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[]

I think the general issue is, that Asciidoc is merely a text formatting tool, which means, if i want it to generate a structured documentation mostly from my code, i would need to provide this structe in my code and in my .adoc file. Documentation generators like Doxygen on the other side recognize this structure and the documenting comments automatically. I value this feature very much, that some generators allow you to write code and pretty documentation side by side, which lowers the overall effort alot. If Asciidoc doesn't allow me to do this in a reasonable way, i will have look for something else.

1 Answer 1

0

I think you would have to write a scraper that puts the comments into a structure, then pull that structure into your AsciiDoc. This way the comments can be internally formatted with AsciiDoc markup, and you can output it in Asciidoctor-generated documents, but you won't need Asciidoctor to read the source files directly.

I would try a system of using one # for non-publishing comments and ## for ones you wish to publish, or vice versa, or append a # to the ones that are for docs publishing. As well as those denoted by the """ notation. Then your scraper can read the block name (uber_func or whatever portion is important) and then scrape the keeper comments and all the literal code, arranging them all in a file. The below file has seen most comments tagged as text, non-keeper comments dropped, and non-comment content as code:

# 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[]

I know this looks hideous, but it is super useful to an AsciiDoc template. For instance, use just:

uber_func::
include::includes/api-stuff.adoc[tags="function__uber_func_form"]
+
include::includes/api-stuff.adoc[tags="function__uber_func_desc"]
+
include::includes/api-stuff.adoc[tags="function__uber_func_body"] 

This would be even better if you parse it to a data format (like JSON or YAML) and then press it into AsciiDoc template dynamically. But you could maintain something like the above if it was not too massive. At a certain size (20+ such records?) you need an intermediary datasource (an ephemeral data file produced by the scraping), and at a certain larger scale (> 100 code blocks/endpoints?), you likely need a system that specializes in API documentation, such as Doxygen, et al.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.