diff options
Diffstat (limited to 'docs/other_options_for_docu_gen.rst')
| -rw-r--r-- | docs/other_options_for_docu_gen.rst | 83 |
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_ |