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.
  10
  11 Rationale
  12 Documentation is just code, and by maintaining the documentation as
  13 source is is possible to generate various forms of output with a
  14 single make.  While it is possible to convert X to Y, a true document
  15 composition language is far better at geneating readable Postscript
  16 output with embedded figures as well as text and tables.
  17
  18 CAUTION:
  19 The RST syntax is as bad as python when it comes to dealing with
  20 spaces.  For example &bold( foo ) will insert spaces after the initial
  21 bold trigger, and before the trailing bold trigger which will throw
  22 the tox validation into a tizzy.  Further,  something like 'void *'
  23 and 'rmr_ '  does as well.  If needed, use the defined escape macro
  24 to add an escape in such situations; it should only generate for RST
  25 and not impact other output formats.