Package: code-guide
Code Guide==========A tool that generates an interactive HTML explanation of how codeworks from unobtrusive markup of comments in the code.  Theexplanation is readable in the source, as well as in the generateddocumentation.Installation============Install with pip:pip install code-guideRunning the Tool================To convert a single file, _example.py_:# This is where we are going to save generated HTMLmkdir outdir# Generate HTML from some example codecode-guide example.py --extract-resources -o outdir/example.htmlRun `code-guide --help` for more help on the command-line options.Converting Multiple Files with Make===================================When converting multiple files, run the translation of source filesinto HTML and the extraction of resources used by all the generatedHTML as separate steps.It's convenient to use Make to coordinate the translation of multiplefiles, as so:EXAMPLES = $(wildcard examples/*.java)EXAMPLE_DOCS = $(EXAMPLES:%.java=docs/%.html)docs: $(EXAMPLE_DOCS) docs/examples/code-guide.css.PHONY: docsdocs/examples/%.html: examples/%.java@mkdir -p $(dir $@)code-guide $< -o $@ -r . -l java -c // -t '(.+).java' '\1.html'docs/examples/code-guide.css:@mkdir -p $(dir $@)code-guide --extract-resources --resource-dir=$(dir $@)How to Mark Up Example Code===========================Mark up regions of code to be explained by adding line comments thatimmediately start with a "|" character at the start of the region, anda line comment that starts with "|." at the end of the region.E.g., in Python:#| This is the startsome_code()#|.In Java://| This is the startSomeCodeFactoryFactoryImpl.getSomeCodeFactory().getSomeCode().run();//|.The rest of this document describes using the tool with a languagethat has line comments starting with "#", but the documentationapplies to just as well languages with a different line-commentsyntax.Adjacent #| comments are treated as a single block of Markdown syntax.Regions can be nested but not overlap.#| This if statement compares two numbers.#|#| It copes with floating point _NaN_ values.if a > b:print "larger"elif a < b:print "smaller"elif a == b:print "the same"else:#| _NaN_ is never equal to another floating point value, not even to _NaN_.print "NaN"#|.#|.The order in which explanations are presented to the reader can becontrolled by adding indices in square brackets at the start of each#| comment block.  Indices start at 1.  Either all or none of theexplanations must have an index.  If no explanations have an index,they are shown in the order they appear in the source code.#| [2] This statement will be explained second.print "goodbye, cruel world."#|.#| [1] This statement will be explained first.sys.exit(1)#|.The generated document can be given an introduction and/or end-note inmarkdown format with a block of adjacent lines that start with #||.If the introduction has a top-level heading, the text of the headingis used as the title of the generated HTML.Only the first and last block of text will be used.  Any others willbe silently ignored (and may cause an error in future versions of thetool).#|| Hello World#|| ===========#||#|| Hello world is traditionally used to illustrate to beginners#|| the most basic syntax of a programming language, or to verify#|| that a language or system is operating correctly.#| This is all that is required in Pythonprint "hello, world"#|.