summaryrefslogtreecommitdiffstats
path: root/docs/other_options_for_docu_gen.rst
diff options
context:
space:
mode:
authorVictor Laza <vlaza@cloudbasesolutions.com>2015-04-16 11:27:04 +0300
committerVictor Laza <vlaza@cloudbasesolutions.com>2015-04-16 11:27:04 +0300
commitb888c0a123226f3eaeccb0e42c43cfba7cc4a91b (patch)
tree4d3cd173dc6a3ba3554803c3acda0d50e25e798a /docs/other_options_for_docu_gen.rst
parent7b5b716dd57ddbd29a8a1c729bac74ed3c83470e (diff)
Split/improved the documentation to enable docu-gen for projects
JIRA: The part with other options tested has been separated, link to PDF has been added, fixed indentation on job-template, added explanation that every commit/merge might affect the docu displayed on wiki Change-Id: Ieb33a08388522cc7d05e155de8f1f5fb9333d4f4 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, 83 insertions, 0 deletions
diff --git a/docs/other_options_for_docu_gen.rst b/docs/other_options_for_docu_gen.rst
new file mode 100644
index 000000000..94ba95e6e
--- /dev/null
+++ b/docs/other_options_for_docu_gen.rst
@@ -0,0 +1,83 @@
+Other options to generate documentation that we tested
+-------------------------------------------------------
+
+**Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf)**
+
+
+Description: This was the first discovered method
+
+- html: using Doxygen plugin + HTML publisher
+ It involves some customization at doxygen level + custom html header/footer
+
+- pdf: it generates a .pdf using latex
+
+- Input files: .md , .rst
+
+- Output: .html & .pdf
+
+- 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
+ - 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
+
+
+
+**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
+
+- 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
+
+- 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
+
+
+
+**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
+
+- 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
+
+- 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
+