Shamusworld >> Repos - ardour-manual/blob - README.md

   1
   2 # The Ardour Manual
   3
   4 This is the project that generates the static ardour manual website available at
   5 [manual.ardour.org](http://manual.ardour.org). The site is built using python 3.
   6
   7 ### Get the code
   8
   9     git clone <repo-url> ardour-manual
  10     cd ardour-manual
  11
  12 ## Structure of the content
  13
  14 There are 2 different types of content:
  15
  16 - a master document which describes the overall structure of the manual
  17 - normal content, which is described in the master document
  18
  19 ### The Master Document
  20
  21 This is a text file (master-doc.txt) which describes the structure of the
  22 manual. It does this through headers which tell the build script where the
  23 content lives, what its relationship to the overall structure is, as well as a
  24 few other things.
  25
  26 All headers have a similar structure, and have to have at least the following
  27 minimal structure:
  28
  29     ---
  30     title: Some Wordy and Expressive Title
  31     part: part
  32     ---
  33
  34 Keywords that go into the header are of the form:
  35
  36           keyword: value
  37
  38 Here are the keywords you can put in, and a brief description of what they do:
  39
  40
  41 | Keyword | Meaning  |
  42 | ------- | -------- |
  43 | title   | Sets the title for the content that follows |
  44 | menu_title | Sets the title for the content that follows which will appear in the menu link sidebar. If this is not specified, it defaults to the value of the `title` keyword |
  45 | part    | Sets the hierarchy for the content that follows. It must be one of the following (listed in order of lowering hierarchy): part, chapter, subchapter, section, subsection.  |
  46 | link    | Sets the unbreakable link to the content that follows. Links in the *content* should be prefixed with a double at-sign (@@) to tell the build system that the link is an internal one |
  47 | include | Tells the build system that the content lives in an external file; these normally live in the `include/` directory. Note that the filename should **not** be prefixed with `include/` |
  48 | exclude | Tells the `implode` and `explode` scripts that file referred to by the `include` keyword should be ignored. Note that the value of this keyword is ignored |
  49 | style   | Sets an alternate CSS stylesheet; the name should match the one referred to (sans the `.css` suffix) in the `source/css` directory |
  50 | uri     | Sets an absolute URI where this page will go in the hierachy of the created website. It does *not* change the document structure |
  51
  52 ### Normal content
  53
  54 Manual content goes into the `include/` directory (or in the Master Document
  55 itself); and consists of normal HTML, sans the usual headers that is normally
  56 seen in regular HTML web pages. Any other content, such as css files, images,
  57 files and fixed pages goes into the `source/` directory.
  58
  59 Adding `source/images/horse.png` makes it available at the url
  60 `/images/horse.png` after publishing it; things work similarly for
  61 `source/files/` and `source/css/`.
  62
  63 ### CSS
  64
  65 The manual uses [Bootstrap](http://getbootstrap.com/) for its global layout, and
  66 a custom CSS (`source/css/app.css`) that contains classes used for keys, menus,
  67 tables, etc... so it is recommanded to have a look at it first, or at least see
  68 how other pages are made to keep the manual consistent in its appearance.
  69
  70 ## More Advanced Stuff
  71
  72 You probably don't want or need to do any of this, but here are some
  73 notes just in case you decide to anyway.
  74
  75 ### Run it locally
  76
  77 You may want the manual available on a machine that doesn't have constant
  78 internet access. You will need `git`, and `python3` installed.
  79
  80 1. Download code and build manual
  81
  82   ```
  83   git clone <repo-url> ardour-manual
  84   cd ardour-manual
  85   ./build.py
  86   ```
  87
  88 2. Install and configure a web server on your machine. Any web server should
  89 work,  Apache, nginx, etc... The following steps are for nginx, using another
  90 server means following the same procedure for the server you decide to use.
  91
  92 3. Install [nginx](http://wiki.nginx.org/Install)
  93
  94 4. Configure nginx server block in `/etc/nginx/sites-available/default`
  95
  96   ```
  97   server {
  98       listen 80;
  99       server_name localhost;
 100
 101       root ...path_to_.../ardour-manual/website;
 102       index index.html;
 103   }
 104   ```
 105
 106 5. Restart nginx server
 107
 108         service nginx restart
 109
 110 6. The manual will now be available at http://localhost
 111
 112 ### Helper scripts: `implode` and `explode`
 113
 114 The `implode` and `explode` scripts exist in order to accomodate different
 115 working styles. `implode` takes all the files referenced by the `include`
 116 keywords in the headers in the Master Document and automagically puts them into
 117 the Master Document in their proper places. Note that any header that has an
 118 `exclude` keyword will remain in the `include/` directory. `explode` does the
 119 inverse of `implode`; it takes all the content in the Master Document and blows
 120 it into individual files in the `include/` directory.
 121
 122 ### Build options
 123
 124 The `build.py` script that builds the manual accepts the following options:
 125 - '-v', or '--verbose', to display the high-level structure of the manual
 126 - '-q', or '--quiet', to suppress all output (overrides -v)
 127 - '-d', or '--devmode', to add content to pages to help developers debug them
 128 (link, file name, URL)