diff options
Diffstat (limited to 'docs/enable_docu_gen.rst')
| -rw-r--r-- | docs/enable_docu_gen.rst | 118 |
1 files changed, 72 insertions, 46 deletions
diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst index 9e764bd03..c3b44956e 100644 --- a/docs/enable_docu_gen.rst +++ b/docs/enable_docu_gen.rst @@ -1,28 +1,34 @@ -How to setup the workflow of documentation build for your project -================================================================== +How to setup the workflow of automatic documentation build for your project +---------------------------------------------------------------------------- -**Setup you repository and then clone locally** - ssh-add your-ssh-key - git clone ssh://<username>@gerrit.opnfv.org:29418/<project> +**Setup you repository and then clone locally**:: + ssh-add your-ssh.key + + git clone ssh://<username>@gerrit.opnfv.org:29418/<project> + + cd <project> + + +**Inside the repository create the following structure:**:: -**Inside the repository create the following structure:** gerrit.opnfv.org/<project> - docs/ - --- docs/main.rst - --- docs/other-docus.rst - --- docs/images/*.png|*.jpg + /main.rst + /other-docus.rst + /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 +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://<username>@gerrit.opnfv.org:29418/releng + Enter the project settings:: cd releng/jjb/<project>/ @@ -37,13 +43,16 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/:: #!/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 + file_cut="${{file%.*}}" + html_file=$file_cut".html" + pdf_file=$file_cut".pdf" + rst2html $file > $html_file + rst2pdf $file -o $pdf_file done + + #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml + **Edit <your-project>.yml**:: @@ -53,7 +62,7 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/:: Make sure you have the job-templates set right -example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" section):: +example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections):: - job-template: name: 'opnfvdocs-daily-{stream}' @@ -66,6 +75,7 @@ example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "bu /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/ + - job-template: name: 'opnfvdocs-verify' ... @@ -73,6 +83,7 @@ example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "bu - shell: !include-raw build-docu.sh + - job-template: name: 'opnfvdocs-merge' ... @@ -84,6 +95,7 @@ example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "bu /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/ + Stage files:: git add build-docu.sh <project>.yml @@ -102,87 +114,101 @@ Send code for review in Gerrit:: **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)** +http://artifacts.opnfv.org/ +example: http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.pdf -**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. +**Scrape content from html artifacts on wiki** +example of what you sould write on wiki, below:: -**Other options:** + {{scrape>http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.html}} -1. Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf) ---------------------------------------------------------------- +NOTE: +------ - Description: +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 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 - - Final destination of generated files needs to be discussed as it will be part of a Bash script in Post-actions. +- pdf: it generates a .pdf using latex - Input files: .md , .rst +- Input files: .md , .rst - Output: .html & .pdf +- Output: .html & .pdf - Pros: +- 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: +- 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 -2. Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals) --------------------------------------------------------------------------------- +**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 +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 - Output: .html & .pdf +- Input files: .xml - Pros: +- 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: +- 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** -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 +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 +- Output: .html & .pdf - Pros: +- Pros: - standard tools: Python Sphinx, LaTeX suite - destination files are generated fast @@ -192,11 +218,11 @@ if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cl - 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: +- 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 |