Category Archives: Documentation

Ace ‘Editor in the Browser’ – Documentation

Ace ‘Editor in the Browser’ – Documentation

The documentation for Ace – where is it ?


The Ace documentation isn’t that hard to find but you do need to know where to look

Ace in the hole

The Ace project provides a customizable, embeddable code editor for web applications. It’s written solely in JavaScript and is really very impressive.

You can see it in action at their demo page (which frankly is a bit bare bones) or at the Cloud9 project for which Ace is the starting point.

Documentation is where ?

You can download the Ace distribution from – you need the ‘Downloads’ button at the top right.

Once you’ve done that you’ll find there’s nothing worth reading in the docs folder within the distribution.

Instead what you need to do is go visit the Ace wiki at Github. It took me a while to work this out (with the help of the Ace user group forum) so I hope it will save some others the trouble.

Sphinx – how to make autodoc really automatic ?

Automating sphinx.ext.autodoc

A tool to help use the ‘autodoc’ facilties of Sphinx.


Sphinx has a great extension,sphinx.ext.autodoc, which imports the modules you want to document and uses the docstrings as the basis for the documentation. A script I’ve just found makes using sphinx.ext.autodoc even easier.

Although the sphinx.ext.autodoc extension reduces the work of creating Sphinx source files a great deal I still found myself having to create a set of files which corresponded to the modules in a project. This was a bit of a bore particularly as I like to start creating documentation early in a project and so modules would come and go during development.

On a number of occasions I wished I had a script to automatically create the source files needed … well it turns out that Etienne Desautels has already done the heavy lifting and written which does just what I want.

Making use of it is completely independent of Sphinx. Just download it from the above location and run it as

>python --help

Usage: [options] <package path> [exclude paths, ...]

Note: By default this script will not overwrite already created files.

 -h, --help            show this help message and exit
 -n HEADER, --doc-header=HEADER
                       Documentation Header (default=Project)
 -d DESTDIR, --dest-dir=DESTDIR
                       Output destination directory
 -s SUFFIX, --suffix=SUFFIX
                       module suffix (default=txt)
 -m MAXDEPTH, --maxdepth=MAXDEPTH
                       Maximum depth of submodules to show in the TOC
 -r, --dry-run         Run the script without creating the files
 -f, --force           Overwrite all the files
 -t, --no-toc          Don't create the table of content file

Most of this is pretty self-explanatory.

My index.rst looks like this :

Welcome to pySourceAid's documentation!


.. toctree::
:maxdepth: 2



.. toctree::
:maxdepth: 20


Indices and tables

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

And that line in the index.rst


… means that autodoc is going to go looking for source files corresponding to each of the modules in a directory called modules. As a result when I run I use a command like this

python --suffix=rst --dest-dir=C:\myproject\docs\source\modules C:\myproject\src

Where the modules are living in C:\myproject\src


This blog post is based on some work done using : Python 2.6 and Sphinx 1.0.5

Sandcastle XML Reference

Sandcastle XML Reference

Handy reference to Sandcastle XML


Hard working Michael Sorens has produced a wall chart documenting the XML used with the Sandcastle Document Generator.

Reference to Sandcastle’s XML Documentation Comments

In a previous post about Sandcastle I mentioned a useful guide to the Sandcastle Documentation Generator written by Micheal Sorens.

I’ve just come across an accompanying wall chart.

Sandcastle XML Reference Sample

Sandcastle XML Reference Sample

The wall chart provides a quick reference to the XML used by a programmer in source code comments to allow Sandcastle to automatically generate documentation.

The wall chart is a good resource for anyone using Sandcastle and is available for download as a PDF here.

EDIT: The link to the wallchart went bad after this post was published. I’ve now amended the link to point to a version of the wallchart which works as at April 2012.

Sandcastle – the whole story !

Sandcastle – the whole story !

Documenting a document generator !


Sandcastle Document Generator is a great tool for producing project documentation but getting it to work can be … challenging ! Here’s some resources to help.

How does this thing work ?

If you’ve used Sandcastle and XML Documentation to automatically produce your .NET project documentation you’ll know:

  • the resulting output is great
  • getting the output can be challenging !

I came across an article by Michael Sorens which very comprehensively documents the process you need to go through.

Taming Sandcastle: A .NET Programmer’s Guide to Documenting Your Code is (as the intro says) “the easy guide to the process that Microsoft never managed, and introduces several applications that help” – it’s so much better than the process I went through when I was first using Sandcastle – I highly recommend it.

XML Documentation ? – How’s that ?

Now backtracking a little. For those who are not fully on the XML Documentation train here are some other good resources:

  • GhostDoc – Great Visual Studio Extension for ‘automagically’ producing XML Documentation of classes; methods; and properties – it’s very good indeed and … it’s free !
  • Within Michaels main article there’s a nice section introducing the benefits of using XML Documentation
  • Having read the intro mentioned above the nice people at Dynicity have produced a very comprehensive referenceto XML Documentation Comments of all the options available.

Sphinx Documentation Generator – Tutorial 2

Sphinx – first project output

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners.


In this second part of my Sphinx Tutorial we use the ‘quickstart’ script provided with Sphinx to quickly produce a basic set of documentation source files.

Our First Sphinx Project

Sphinx has a great way to get you started and that’s the ‘quickstart’ script (you’ll find in the Scripts directory of your Python installation). Quickstart walks you through a series of questions to produce a basic set of the files you’ll need to produce your documentation.

Quickstart is pretty easy to use and even more so when your aim is to produce something very basic (which is the aim of this tutorial).

We’ll just step through the more important bits here :

Specify where you want the Documentation to be created

Sphinx is going to create some files and a few directories so choose where you want those to be created :
Enter the root path for documentation.
> Root path for the documentation [.]: C:\data\src\Sphinx\Test1

Specify a name for the Documentation:

What ever name you choose will appear in various places in the documentation so choose something you’re happy with

The project name will occur in several places in the built documentation.
> Project name: Sphinx Tutorial
> Author name(s): Richard Shea

Specify a version for the Documentation:

Similarly you’ll get the version number appearing in various parts of the output documenation

> Project version: 1.0.0

Specify if you want any clever stuff:

Sphinx is able to do all sorts of clever stuff apart from interpreting your RST files into beautiful output. We don’t want any of that for the first part of the tutorial so say ‘no’ to all of this.

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:

Make it easy on yourself (at least to start with)

It’s perfectly reasonable to use build the Sphinx output by providing your own command line options but to get started with it’s helpful to allow Sphinx to help a little so say ‘yes’ to a .BAT or a makefile (depending on what’s your choice of poison).

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:

The results of quickstart

So after all that what have we got ? Well we specified C:\data\src\Sphinx\Test1 as the output path and if we look in there we find we’ve got a build and a source directory (as well as the Makefile and make.bat we asked for). What we’re interested in to start with is source\index.rst.

Open it up in a text editor and you’ll see it looks like this :
.. Sphinx Tutorial documentation master file, created by
sphinx-quickstart on Sun Nov 1 18:08:19 2009.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to Sphinx Tutorial's documentation!


.. toctree::
:maxdepth: 2

Indices and tables

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Next Steps

In the next part of this series, Sphinx – Absolute Beginners – Part 3, we’ll see how to make this file into either HTML or PDF output. In later parts of the series we’ll see how to use your existing Python code comments to produce automated documentation of your Python code.

Sphinx Documentation Generator – Tutorial 1

Sphinx – Absolute Beginners – Part 1

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners


Sphinx is a great tool that makes it easy to create good looking documentation in a range of output formats. If you’re a Python programmer it also makes it easy to use your existing docstring comments to form the basis of your documentation.

I’ve found using Sphinx for the first time a little difficult as much of the documentation seems to assume you know certain things. This series of posts provides a tutorial for the absolute beginner.

Ground Rules (for impatient programmers)

Now at this stage there’s a couple of things that are well worth knowing !

  • Sphinx is good at auto-documenting Python code but that’s not its primary role. If you’re a Python programmer looking to auto-document your code it takes a while to understand that a lot of the facilities in Sphinx are nothing to do with what you’re after and that can be confusing.
  • In Sphinx-land ‘the source files’ refer to the documentation configuration files. This confused me for a while whenever the term ‘source files’ was used I thought it meant my python source files.

Getting Spinx Installed

The prerequisites part of the Sphinx doco does a good job here but in summary:

  • You want to have installed Python 2.4 or better
  • Grab the source from the Sphinx Python Project Page or …
  • … just use easy_install -U Sphinx

Next Steps

Sphinx has a great way to get you started and that’s the ‘quickstart’ script. In the next part of this tutorial series we’ll cover how to quickly and easily produce your first Sphinx project.