This is the project that generates the static ardour manual website available at manual.ardour.org. The site is built using python 3.

git clone <repo-url> ardour-manual
cd ardour-manual

There are 2 different types of content:

• a master document which describes the overall structure of the manual
• normal content, which is described in the master document

This is a text file (master-doc.txt) which describes the structure of the manual. It does this through headers which tell the build script where the content lives, what its relationship to the overall structure is, as well as a few other things.

All headers have a similar structure, and have to have at least the following minimal structure:

---
title: Some Wordy and Expressive Title
part: part
---

Keywords that go into the header are of the form:

  keyword: value

Here are the keywords you can put in, and a brief description of what they do:

Manual content goes into the include/ directory (or in the Master Document itself); and consists of normal HTML, sans the usual headers that is normally seen in regular HTML web pages. Any other content, such as css files, images, files and fixed pages goes into the source/ directory.

Adding source/images/horse.png makes it available at the url /images/horse.png after publishing it; things work similarly for source/files/ and source/css/.

The manual uses Bootstrap for its global layout, and a few custom CSS files that contains classes used for keys, menus, tables, etc... so it is recommanded to have a look at it first, or at least see how other pages are made to keep the manual consistent in its appearance:

• source/css/common.css contains shared classes between all media and is included everywhere
• source/css/screen.css adds classes used for screen display (html)
• source/css/pdf.css adds classes used for print (pdf)
• source/css/luadocs.css adds classes used in the Lua script documentation

You probably don't want or need to do any of this, but here are some notes just in case you decide to anyway.

You may want the manual available on a machine that doesn't have constant internet access. You will need git, python3 and cherrypy python module installed.

1. Download code and build manual

git clone <repo-url> ardour-manual
cd ardour-manual
./build.py

2. Run the following:

./servit.py

3. The manual will now be available at http://127.0.0.1:8080

(Ctrl-c to quit the server).

The implode and explode scripts exist in order to accomodate different working styles. implode takes all the files referenced by the include keywords in the headers in the Master Document and automagically puts them into the Master Document in their proper places. Note that any header that has an exclude keyword will remain in the include/ directory. explode does the inverse of implode; it takes all the content in the Master Document and blows it into individual files in the include/ directory.

The build.py script that builds the manual accepts the following options:

• '-v', or '--verbose', to display the high-level structure of the manual
• '-q', or '--quiet', to suppress all output (overrides -v)
• '-d', or '--devmode', to add content to pages to help developers debug them (link, file name, URL)
• '-n', or '--nopdf', to prevent the build script from generate a PDF from the content