doc/src/rtd/README

   1
   2 This directory contains source for the project mandated "read the docs"
   3 .rst documentation.  The Makefile will both build the doc from the source
   4 here and "install" it into the docs directory at the repo root.  While
   5 it is not good practice, the generated .rst files must be checked into
   6 the repo and committed with changes to the source.
   7
   8 The command 'make all' should be all that is needed to build the
   9 rtd documentation. Follow that with 'make publish' to actually move
  10 the .rst files into the docs directory at the root; only the changed
  11 files are moved.
  12
  13 Adding A New Man Page
  14 WHen a new manual page is added to the source (../man), it must be
  15 added to the list in the user's guide source in this directory.
  16
  17 Rationale
  18 Documentation is just code, and by maintaining the documentation as
  19 source is is possible to generate various forms of output with a
  20 single make.  While it is possible to convert X to Y, a true document
  21 composition language is far better at geneating readable Postscript
  22 output with embedded figures as well as text and tables.
  23
  24 CAUTION:
  25 The RST syntax is as bad as python when it comes to dealing with
  26 spaces.  For example &bold( foo ) will insert spaces after the initial
  27 bold trigger, and before the trailing bold trigger which will throw
  28 the tox validation into a tizzy.  Further,  something like 'void *'
  29 and 'rmr_ '  does as well.  If needed, use the defined escape macro
  30 to add an escape in such situations; it should only generate for RST
  31 and not impact other output formats.