docs/other_options_for_docu_gen.rst

   1 Other options to generate documentation that we tested
   2 -------------------------------------------------------
   3
   4 **Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf)**
   5
   6 Description: This was the first discovered method
   7
   8 * html: using Doxygen plugin + HTML publisher
   9   It involves some customization at doxygen level + custom html header/footer
  10
  11 * pdf: it generates a .pdf using latex
  12 * Input files: .md , .rst
  13 * Output: .html & .pdf
  14 * Pros:
  15
  16         - standard tools: doxygen, html publisher, LaTeX suite
  17         - doxygen plugin available in Jenkins, you just need to install it; html publisher plugin available in Jenkins, you just need to install it
  18         - destination files are generated fast
  19         - standard reStructuredText or Markdown
  20
  21 * Cons:
  22
  23         - takes some time to customize the output in matters of template, requires custom html header/footer
  24         - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
  25
  26 * Tested: roughly, functional tests only
  27
  28 **Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals)**
  29
  30 Description: It represents the standard tool to generate Openstack documentation manuals, uses maven, maven plugins, clouddocs-maven-plugins; location of finally generated files is the object of a small Bash script that will reside as Post-actions
  31
  32 * Input files: .xml
  33 * Output: .html & .pdf
  34 * Pros:
  35
  36         - quite easy for initial setup
  37         - uses openstack documentation generation flows as for openstack-manuals (clouddocs-maven-plugin), maven installs all you need generate the documentation
  38
  39 * Cons:
  40
  41         - could be tricky to generate a custom layout, knowledge about Maven plugins required, .pom editing
  42         - dependent of multiple maven plugins
  43         - input files are .xml and xml editing knowledge is required
  44
  45 * Tested: roughly, functional tests only
  46
  47 **Sphinx & LaTeX suite**
  48
  49 Description: The easiest to install, the cleanest in matter of folder & files structure, uses standard tools available in repositories; location of finally generated files is the object of a small Bash script that will reside as Post-actions
  50
  51 * Input files: .rst as default
  52 * Output: .html & .pdf
  53 * Pros:
  54
  55         - standard tools: Python Sphinx, LaTeX suite
  56         - destination files are generated fast
  57         - standard reStructuredText as default; other inputs can be configured
  58         - Sphinx's installation is very clean in matters of folder structure; the cleanest from all tested variants
  59         - latex suite is also easy to install via yum/apt and available in general repos
  60         - everyone is migration from other tools to Spinx lately; it provides more control and better looking documentation
  61         - can be used also for source-code documentation, specially if you use Python
  62
  63 * Cons:
  64
  65         - takes some time to customize the output in matters of template, requires custom html header/footer
  66         - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
  67
  68 * Tested: roughly, functional tests only
  69
  70
  71 **Documentation tracking**
  72
  73 Revision: _sha1_
  74
  75 Build date:  _date_
  76