summaryrefslogtreecommitdiffstats
path: root/docs/other_options_for_docu_gen.rst
diff options
context:
space:
mode:
authorVictor Laza <vlaza@cloudbasesolutions.com>2015-04-20 11:16:55 +0300
committerVictor Laza <vlaza@cloudbasesolutions.com>2015-04-20 13:54:43 +0300
commitb9eb7fc29d29301e2802544a614bfd77e78f52b4 (patch)
tree4be7bae44f19e63cb8ad4a29ea26b16e39d4faf5 /docs/other_options_for_docu_gen.rst
parent66406698441846c2c1969fe8daeb5ec7e16fd298 (diff)
Updated docs/enable_docu_gen.rst to include the new updated script
JIRA: Updated docs/enable_docu_gen.rst to include the new updated script and added **Documentation trackin** to all docs in opnfvdocs Change-Id: Ifc0390b8f5b96290f37143a49b543ce5e123ed24 Signed-off-by: Victor Laza <vlaza@cloudbasesolutions.com>
Diffstat (limited to 'docs/other_options_for_docu_gen.rst')
-rw-r--r--docs/other_options_for_docu_gen.rst83
1 files changed, 41 insertions, 42 deletions
diff --git a/docs/other_options_for_docu_gen.rst b/docs/other_options_for_docu_gen.rst
index 2a050a0d3..73d38dd92 100644
--- a/docs/other_options_for_docu_gen.rst
+++ b/docs/other_options_for_docu_gen.rst
@@ -5,72 +5,71 @@ Other options to generate documentation that we tested
Description: This was the first discovered method
-- html: using Doxygen plugin + HTML publisher
+* html: using Doxygen plugin + HTML publisher
It involves some customization at doxygen level + custom html header/footer
-- pdf: it generates a .pdf using latex
+* pdf: it generates a .pdf using latex
+* Input files: .md , .rst
+* Output: .html & .pdf
+* Pros:
-- Input files: .md , .rst
+ - 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
+ - destination files are generated fast
+ - standard reStructuredText or Markdown
-- Output: .html & .pdf
+* Cons:
-- Pros:
+ - 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)
- - 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
- - 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
- - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
-
-- Tested: roughly, functional tests only
+* 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
-- Input files: .xml
+* Input files: .xml
+* Output: .html & .pdf
+* Pros:
-- Output: .html & .pdf
+ - 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
-- Pros:
+* Cons:
- - 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
+ - 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
-- Cons:
-
- - 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
-
-- Tested: roughly, functional tests only
+* Tested: roughly, functional tests only
**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
-- Input files: .rst as default
+* Input files: .rst as default
+* Output: .html & .pdf
+* Pros:
+
+ - 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
+ - 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
+ - can be used also for source-code documentation, specially if you use Python
-- Output: .html & .pdf
+* Cons:
-- Pros:
+ - 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)
- - 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
- - 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
- - can be used also for source-code documentation, specially if you use Python
+* Tested: roughly, functional tests only
-- Cons:
- - 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)
+**Documentation tracking**
-- Tested: roughly, functional tests only
+Revision: _sha1_
+Build date: _date_