Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install code-guide

How to install code-guide

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install code-guide
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
Windows (64-bit)
Mac OS X (10.5+)
Linux (32-bit)
Linux (64-bit)
1.0.2 Available View build log
Apache 2.0. Bootstro is used under the MIT ...
Lastest release
version 1.0.2 on Jan 9th, 2014

Code Guide

A tool that generates an interactive HTML explanation of how code works from unobtrusive markup of comments in the code. The explanation is readable in the source, as well as in the generated documentation.


Install with pip:

pip install code-guide

Running the Tool

To convert a single file, _example.py_:

# This is where we are going to save generated HTML mkdir outdir

# Generate HTML from some example code

System Message: WARNING/2 (<string>, line 27)

Block quote ends without a blank line; unexpected unindent.

code-guide example.py --extract-resources -o outdir/example.html

Run 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 files into HTML and the extraction of resources used by all the generated HTML as separate steps.

It's convenient to use Make to coordinate the translation of multiple files, as so:

EXAMPLES = $(wildcard examples/*.java)

System Message: WARNING/2 (<string>, line 56); backlink

Inline emphasis start-string without end-string.

EXAMPLE_DOCS = $(EXAMPLES:%.java=docs/%.html)

docs: $(EXAMPLE_DOCS) docs/examples/code-guide.css .PHONY: docs

docs/examples/%.html: examples/%.java
@mkdir -p $(dir $@) code-guide $< -o $@ -r . -l java -c // -t '(.+).java' '1.html'
@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 that immediately start with a "|" character at the start of the region, and a line comment that starts with "|." at the end of the region.

System Message: WARNING/2 (<string>, line 61); backlink

Inline substitution_reference start-string without end-string.

E.g., in Python:

#| This is the start some_code() #|.

In Java:

//| This is the start SomeCodeFactoryFactoryImpl.getSomeCodeFactory().getSomeCode().run(); //|.

System Message: WARNING/2 (<string>, line 74); backlink

Inline substitution_reference start-string without end-string.

The rest of this document describes using the tool with a language that has line comments starting with "#", but the documentation applies to just as well languages with a different line-comment syntax.

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:

System Message: ERROR/3 (<string>, line 90)

Unexpected indentation.
print "larger"

System Message: WARNING/2 (<string>, line 91)

Block quote ends without a blank line; unexpected unindent.
elif a < b:
print "smaller"
elif a == b:
print "the same"
#| _NaN_ is never equal to another floating point value, not even to _NaN_. print "NaN" #|.

System Message: WARNING/2 (<string>, line 99)

Definition list ends without a blank line; unexpected unindent.


The order in which explanations are presented to the reader can be controlled by adding indices in square brackets at the start of each #| comment block. Indices start at 1. Either all or none of the explanations 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 in markdown format with a block of adjacent lines that start with #||. If the introduction has a top-level heading, the text of the heading is used as the title of the generated HTML.

Only the first and last block of text will be used. Any others will be silently ignored (and may cause an error in future versions of the tool).

#|| 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 Python print "hello, world" #|.

Subscribe to package updates

Last updated Jan 9th, 2014

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.