Remark

Back to Homepage of Kalle Rutanen

Remark is a Python library to generate html documentation for software libraries. Naturally, Remark is documented with Remark, the results of which you are inspecting right now.

Usage

From the console (Windows, Linux, Unix, ...):

remark.py [options] inputDirectory outputDirectory [filesToCopy...]

See the installation instructions below.

News

11.03.2010: Released Remark 1.2.0

Core

Allowed free positioning of Remark macros.
Added the ability to invoke macros via inline parameters.
Added explicit control over parameter and output expansion behavior in macro invocation.
Allowed local variables for macros.
Added set_outer, add_outer, and outer commands to set, append, and retrieve variables at outer scopes, respectively.
Allowed parameter passing for variables to turn them into user-defined text transformations.
Variables can now be retrieved simply by their name, rather than having to use get.
Added set_many command to set variables easily.
Fixed a bug in filesToCopy pattern matching: a file was copied only if it matched all patterns.

Macros

Added FileLink macro to generate links with the link description set to the filename of the target.
Added the implicit file searching algorithm for pure filenames into various macros.
DocChildren and Index macros now use 2 or 3 columns to list the items if there are more than 7 of them.
Added Html macro to embed html directly.
Added Gallery macro to generate image galleries.
Added Verbatim macro to reinterpret text as verbatim content.
Added DirectoryLink macro to generate links to the containing directories of files.
Added Copy macro to copy the input without changes.
Added Ref macro to return the relative filenames of the output documents.
Removed SkipExpansion macro. Its effect can be obtained with the Copy macro.

Interface

Added the option to merge a prologue file to the beginning of each document template.

Additional dependencies

Dependence to Python Imaging Library via Gallery macro.
Optional dependence to Highslide javascript library via Gallery macro.

More news

Download

Download Remark 1.2.0

Note on web-browsers

This documentation uses MathML to display inlined mathematics. Unfortunately not all browsers support MathML natively, including Internet Explorer. In this case you will not be able to see the mathematical expressions at all. While there is a plug-in available (MathPlayer) for adding this capability to Internet Explorer, in our tests this combination crashed the browser when viewing these pages. According to Wikipedia, some major web-browsers that currently display MathML natively include Mozilla Firefox, Opera, and Camino. At this point we can't do anything else than to direct you to use these browsers to view these pages.

Acknowledgements

Remark was programmed under funding from the Finnish Foundation for Technology Promotion

Remark was preceded by a similar implementation called LightMark programmed by Juho Hämäläinen. The ideas gathered and tested in that implementation was the basis on which Remark was built. He should be attributed the idea of using Markdown for writing the documentation.

Learn more