I want to use Asciidoctor for documenting code source modules. But not by using a separate .adoc file and including parts of the source file but by using the source file itself to be processed by Asciidoctor.
All Asciidoc formatted content will be started by a line comment (of the programming language) which is followed by a special character, for example an exclamation mark like used by Doxygen. The code itself will be shown as a source code block in the processed output file.
Very small example in Python:
#! = Hello World module
#! John Doe
#! v1.0, 2017-01-01
#!
#! This program just prints 'Hello World' and the current date and time.
#!
#! == Import needed libraries
#!
#! [source,python]
#! ----
import datetime
#! ----
#!
#! == Main program
#!
#! [source,python]
#! ----
print("Hello World.") # <1>
print "Current date and time:"
print str(datetime.datetime.now()) # <2>
#! ----
#! <1> Use 'print' function to output text
#! <2> This converts current date and time to a string and prints it
#!
All this would need is Asciidoctor to remove the sequence "#! " from the start of each line before processing the file. This would also be useful as an option for include::[]. The sequence should be configurable to support different language comments.
Is this already possible using an exisiting Asciidoctor option?
If not I would suggest it as a very useful feature.
Thanks,
Robert
Locked
