The scuff-em documentation system

The documentation for scuff-em is maintained in the form of plain-text (markdown) files stored in the doc subdirectory of the scuff-em repository. These files are processed by the wonderful open-source MkDocs system to build the web-based documentation hierarchy.

A major reason for this choice of documentation system is to make it easy for scuff-em users to edit the existing documentation and to contribute new documentation. If you discover incorrect or incomplete portions of the documentation, or if you would like to add new documentation, please consider contributing to scuff-em by making the relevant changes in the doc subdirectory of your scuff-em repository, then submitting a pull request on GitHub.

Building and serving your own local copy of the documentation

It's easy to build your own local copy of the entire scuff-em documentation hierarchy, which you can then view offline. This allows you to access the documentation without Internet access, and also to preview any changes you might make to the documentation before submitting them in the form of a pull request.

One-time only setup operations

To build the scuff-em documentation, you will need a python installation on your system, and you will need the mkdocs and python-markdown-math packages. On my system I was able to install these using the following commands:

% sudo pip install mkdocs
% sudo pip install --upgrade pyinotify
% git clone https://github.com/mitya57/python-markdown-math.git
% cd python-markdown-math 
% python setup.py build
% sudo python setup.py install

Building the documentation

To build the documentation, starting from the top-level directory of your scuff-em repository, simply say

% cd doc
% mkdocs build

This will create the HTML hierarchy in the subdirectory doc/site.

Serving the documentation

A wonderfully convenient feature provided by MkDocs is the ability to serve your local version of the documentation locally to a web browser running on your machine, without having to mess around with configuring apache or any other webserver software. To do this, starting from the doc subdirectory of the scuff-em repository you simply go like this:

% cd doc
% mkdocs serve

Then direct your favorite web browser to the site 127.0.0.1:8000, i.e.

% google-chrome 127.0.0.1:8000

This should pull up the top-level page of the scuff-em documentation tree, with internal links pointing to your local copies of the various pages.

The great thing about this is that, whenever you save changes to a file in the doc subdirectory of your scuff-em repository, the documentation is automatically rebuilt and the webserver automatically refreshed. This allows you to edit the scuff-em documentation in WYSIWIG fashion, simply by working on an .md file in a text editor in one window, while having a web browser open to the corresponding subpage of 127.0.0.1:8000 in another window. Then, every time you save changes to the text file, the web page is automatically updated! I love this brilliant system.