From a7b9a43192c9d4c1245839e28eb5fc0748122aa3 Mon Sep 17 00:00:00 2001 From: Uli Kleber Date: Fri, 18 Dec 2015 11:35:35 +0100 Subject: Fix Line Length etc for existing docs Jira: DOCS-68 Fixing errors reported by the new tooling. platformoverview/index.rst will be fixed with the new platformoverview document (see separate patch) corrected importing logo images Change-Id: I08f73dcfeef4f2ff3a38a0372491a46798b4026b Signed-off-by: Uli Kleber --- docs/arno/other_options_for_docu_gen.rst | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) (limited to 'docs/arno/other_options_for_docu_gen.rst') 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: -- cgit 1.2.3-korg