This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
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.


Installation
============

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

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 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.

E.g., in Python:

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


In Java:

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

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:
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 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"
#|.
Release History

Release History

1.0.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
code-guide-1.0.2.tar.gz (126.7 kB) Copy SHA256 Checksum SHA256 Source May 30, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting