Remark
======

[Back to Homepage of Kalle Rutanen][Back]

[Back]: http://kaba.hilvi.org

_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 [[remark_version]]. The latest version can be found from [here][RemarkHomepage]. 

Remark is licensed under the [MIT license][MIT].

[RemarkHomepage]: http://kaba.hilvi.org/remark

[MIT]: http://opensource.org/licenses/MIT

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][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

[Pip]: https://pip.pypa.io/en/latest/installing.html

Quick start
-----------

### Hello, world!

* Create a dedicated directory for the example, say `~/hello`.

* Write the following into `~/hello/hello.txt`:

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

	Apples are great.

* Type in console, in directory `~/hello`:

	remark.py . docs "*.txt" "-xdocs/*"

* Open `~/hello/docs/hello.htm` in a browser.

### Configuration file

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

[[set Code.type]]: json

[[Code]]:
	{
		"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 [GitHub][] in a [Git][] repository.

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

[GitHub]: http://github.com/kaba2/remark
[Git]: https://git-scm.com/
