summaryrefslogtreecommitdiffstats
path: root/docs/arno/other_options_for_docu_gen.rst
diff options
context:
space:
mode:
authorChristopher Price <christopher.price@ericsson.com>2015-12-18 14:08:53 +0000
committerGerrit Code Review <gerrit@172.30.200.206>2015-12-18 14:08:53 +0000
commit300d3d820d4af1a69117bab1343a30d470b06441 (patch)
tree96d68a84ff7967740b6225a1488ff17cdd7efa58 /docs/arno/other_options_for_docu_gen.rst
parentf4b9495286c89c86846c666d1960cce395eebed1 (diff)
parenta7b9a43192c9d4c1245839e28eb5fc0748122aa3 (diff)
Merge "Fix Line Length etc for existing docs"
Diffstat (limited to 'docs/arno/other_options_for_docu_gen.rst')
-rw-r--r--docs/arno/other_options_for_docu_gen.rst29
1 files changed, 21 insertions, 8 deletions
diff --git a/docs/arno/other_options_for_docu_gen.rst b/docs/arno/other_options_for_docu_gen.rst
index ea6ad2598..596f39429 100644
--- a/docs/arno/other_options_for_docu_gen.rst
+++ b/docs/arno/other_options_for_docu_gen.rst
@@ -14,31 +14,39 @@ Description: This was the first discovered method
* Pros:
- standard tools: doxygen, html publisher, LaTeX suite
- - doxygen plugin available in Jenkins, you just need to install it; html publisher plugin available in Jenkins, you just need to install it
+ - doxygen plugin available in Jenkins, you just need to install it;
+ html publisher plugin available in Jenkins, you just need to install it
- destination files are generated fast
- standard reStructuredText or Markdown
* Cons:
- - takes some time to customize the output in matters of template, requires custom html header/footer
+ - takes some time to customize the output in matters of template,
+ requires custom html header/footer
- latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
* Tested: roughly, functional tests only
**Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals)**
-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
+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
* Input files: .xml
* Output: .html & .pdf
* Pros:
- quite easy for initial setup
- - uses openstack documentation generation flows as for openstack-manuals (clouddocs-maven-plugin), maven installs all you need generate the documentation
+ - uses openstack documentation generation flows as for
+ openstack-manuals (clouddocs-maven-plugin),
+ maven installs all you need generate the documentation
* Cons:
- - could be tricky to generate a custom layout, knowledge about Maven plugins required, .pom editing
+ - could be tricky to generate a custom layout,
+ knowledge about Maven plugins required, .pom editing
- dependent of multiple maven plugins
- input files are .xml and xml editing knowledge is required
@@ -46,7 +54,10 @@ Description: It represents the standard tool to generate Openstack documentation
**Sphinx & LaTeX suite**
-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
+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
* Input files: .rst as default
* Output: .html & .pdf
@@ -55,9 +66,11 @@ Description: The easiest to install, the cleanest in matter of folder & files st
- standard tools: Python Sphinx, LaTeX suite
- destination files are generated fast
- standard reStructuredText as default; other inputs can be configured
- - Sphinx's installation is very clean in matters of folder structure; the cleanest from all tested variants
+ - Sphinx's installation is very clean in matters of folder structure;
+ the cleanest from all tested variants
- latex suite is also easy to install via yum/apt and available in general repos
- - everyone is migration from other tools to Spinx lately; it provides more control and better looking documentation
+ - everyone is migration from other tools to Spinx lately;
+ it provides more control and better looking documentation
- can be used also for source-code documentation, specially if you use Python
* Cons: