Remark

Back to Homepage of Kalle Rutanen

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

This is version 1.7.6. The latest version can be found from here.

Remark is licensed under the MIT license.

Usage

From the command-line (Windows, Linux, Mac OS X, …):

remark.py inputDirectory outputDirectory (option|file-glob)*

Linux and Mac OS X

The shells on Linux and Mac OS X expand the globs (e.g *.txt) before running an executable (unless the globs do not match anything in the current directory). Therefore, on the command-line the globs should always be provided in the form "*.txt", to defer the glob-expansion from the shell to Remark.

Installation

In the following we will assume that Python and pip have already been installed.

Mac OS X

From the command-line, run

sudo pip install remark

Linux

From the command-line, run with administrator rights

pip install remark

Windows

From the command-line, run

pip install remark

Quick start

Hello, world!

Hello, world!
=============

Apples are great.
remark.py . docs "*.txt" "-xdocs/*"

Configuration file

To avoid specifying reoccuring command-line parameters, gather them into a configuration file. Write the following into ~/hello/remark_config.json:

{
    "disable" : [],
    "flags" : [],
    "include" : ["*.txt"],
    "exclude" : ["docs/*"]
}

The example can now be built in directory ~/hello by

remark.py . docs

Source code

The source code for Remark is hosted on BitBucket in a Mercurial repository. Assuming you have Mercurial installed, the repository can be cloned from the command-line by

hg clone https://bitbucket.org/kaba2/remark

The source code is meant for developers; it is not needed to install Remark.

Issue tracker

The issue tracker for Remark is hosted on Bitbucket in here.

Learn more