From 131605f80924c2e1cd49c1797661f84362dc1a84 Mon Sep 17 00:00:00 2001 From: Victor Laza Date: Wed, 15 Apr 2015 22:42:27 +0300 Subject: Moved main.rst & enable_docu_gen.rst under docs/ JIRA: Moved main.rst & enable_docu_gen.rst under docs/ Change-Id: I597a465e8f5cc915430b3f39163434e6a981b666 Signed-off-by: Victor Laza --- enable_docu_gen.rst | 187 ---------------------------------------------------- 1 file changed, 187 deletions(-) delete mode 100644 enable_docu_gen.rst (limited to 'enable_docu_gen.rst') diff --git a/enable_docu_gen.rst b/enable_docu_gen.rst deleted file mode 100644 index a9cd01253..000000000 --- a/enable_docu_gen.rst +++ /dev/null @@ -1,187 +0,0 @@ -How to setup the workflow of documentation build for your project -================================================================== - -**Setup you repository and then clone locally** - - ssh-add your-ssh-key - git clone ssh://@gerrit.opnfv.org:29418/ - - -**Inside the repository create the following structure:** - gerrit.opnfv.org/ - docs/ - --- docs/main.rst - --- docs/other-docus.rst - --- docs/images/*.png|*.jpg - - -**In order to obtain a nice .html & .pdf at then end you must write you documentation using reSt markup** - - a quick guide: http://docutils.sourceforge.net/docs/user/rst/quickref.html - - -**Clone the releng repository so you can created jobs for JJB** - -git clone ssh://@gerrit.opnfv.org:29418/releng - -cd releng/jjb// - -Create build-docu.sh with the following content: -------------------------------------------------- - -``#!/bin/bash -set -xv -for file in $(find . -type f -iname '*.rst'); do - file_cut="${{file%.*}}" - html_file=$file_cut".html" - pdf_file=$file_cut".pdf" - rst2html $file > $html_file - rst2pdf $file -o $pdf_file -done`` - - - -Edit .yml and make sure you have the job-templates set as in the example below: - - -``- job-template: - name: 'opnfvdocs-daily-{stream}' - - builders: - - shell: - !include-raw build-docu.sh - - shell: | - gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ - gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/ - - - -- job-template: - name: 'opnfvdocs-verify' - - builders: - - shell: - !include-raw build-docu.sh - - - -- job-template: - name: 'opnfvdocs-merge' - - builders: - - shell: - !include-raw build-docu.sh - - shell: | - gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ - gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/`` - - - -git add build-docu.sh .yml - -git commit --signoff #add the proper message to commit - -git review -v - - - -**Create the documentation using the recommended structure in your repository and submit to gerrit for review** - -**Jenkins will take over and produce artifacts in the form of .html & .pdf** -Jenkins has the proper packages installed in order to produce the artifacts. - -**Artifacts are stored on Google Storage (still to decide where, structure and how to present them)** - - - -**NOTE:** In order to generate html & pdf documentation the needed packages are rst2pdf & python-docutils -if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cleanest as a solution. - - - -**Other options:** - - -1. Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf) ---------------------------------------------------------------- - - Description: - -- html: using Doxygen plugin + HTML publisher - It involves some customization at doxygen level + custom html header/footer - - - pdf: it generates a .pdf using latex - - Final destination of generated files needs to be discussed as it will be part of a Bash script in Post-actions. - - 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 tbeeingests only - - - -2. 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 - - - -3. 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 - - -- cgit 1.2.3-korg