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
  13 - Input files: .md , .rst
  14
  15 - Output: .html & .pdf
  16
  17 - Pros:
  18
  19  - standard tools: doxygen, html publisher, LaTeX suite
  20  - doxygen plugin available in Jenkins, you just need to install it; html publisher plugin available in Jenkins, you just need to install it
  21  - destination files are generated fast
  22  - standard reStructuredText or Markdown
  23
  24 - Cons:
  25
  26  - takes some time to customize the output in matters of template, requires custom html header/footer
  27  - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
  28
  29 - Tested: roughly, functional tests only
  30
  31 **Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals)**
  32
  33 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
  34
  35 - Input files: .xml
  36
  37 - Output: .html & .pdf
  38
  39 - Pros:
  40
  41  - quite easy for initial setup
  42  - uses openstack documentation generation flows as for openstack-manuals (clouddocs-maven-plugin), maven installs all you need generate the documentation
  43
  44 - Cons:
  45
  46  - could be tricky to generate a custom layout, knowledge about Maven plugins required, .pom editing
  47  - dependent of multiple maven plugins
  48  - input files are .xml and xml editing knowledge is required
  49
  50 - Tested: roughly, functional tests only
  51
  52 **Sphinx & LaTeX suite**
  53
  54 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
  55
  56 - Input files: .rst as default
  57
  58 - Output: .html & .pdf
  59
  60 - Pros:
  61
  62  - standard tools: Python Sphinx, LaTeX suite
  63  - destination files are generated fast
  64  - standard reStructuredText as default; other inputs can be configured
  65  - Sphinx's installation is very clean in matters of folder structure; the cleanest from all tested variants
  66  - latex suite is also easy to install via yum/apt and available in general repos
  67  - everyone is migration from other tools to Spinx lately; it provides more control and better looking documentation
  68  - can be used also for source-code documentation, specially if you use Python
  69
  70 - Cons:
  71
  72  - takes some time to customize the output in matters of template, requires custom html header/footer
  73  - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
  74
  75 - Tested: roughly, functional tests only
  76