From e2155e6f266e1c9af5d3e4dc625cd2d4adf4de79 Mon Sep 17 00:00:00 2001 From: Victor Laza Date: Tue, 14 Apr 2015 17:44:42 +0300 Subject: Enable docu-gen for projects & main.rst JIRA: Adding the guide to enable docu-gen for projects and main.rst moved from docs/ Change-Id: Iccce14028525157fd71149ee1ab408c39eeaf087 Signed-off-by: Victor Laza --- docs/main.rst | 95 -------------------------- enable_docu_gen.rst | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++ main.rst | 95 ++++++++++++++++++++++++++ 3 files changed, 282 insertions(+), 95 deletions(-) delete mode 100644 docs/main.rst create mode 100644 enable_docu_gen.rst create mode 100644 main.rst diff --git a/docs/main.rst b/docs/main.rst deleted file mode 100644 index 49ac4329b..000000000 --- a/docs/main.rst +++ /dev/null @@ -1,95 +0,0 @@ -Project Name: Documentation -============================ - -- Proposed name for the project: ''opnfv documentation'' -- Proposed name for the repository: ''opnfvdocs'' -- Project Categories: Documentation - -Project description: ---------------------- - -- Produce documentation for OPNFV releases including but not limited to: - - - Release notes - - Installation guide - - User guide - - - Any relevant references and interface specifications for OPNFV projects or components. - - - Include any architecture diagrams or specifications, reference to OPNFV requirements list. - - Provide guidelines and tooling for documentation handling across all OPNFV projects - -Scope: -------- - -- Set up a structure, and a template, for document development with source control (same as source code). Leveraging upstream documentation structure and tools. -- Following as close as possible the same contribution process & tools as our source code -- Structure OPNFV documentation logically -- Develop initial set of release documents: - - - Release note - - Install guide - - User Guide - - API reference (if there is content in release 1) - - Interface specification (if there is content in release 1) - -- Provide language options for documentation where applicable: In first release English only, Wiki (via HTML scraping from Gerrit), and PDF. -- Provide tooling and processes for OPNFV projects to implement and follow for consistency - -Dependencies: --------------- - -- All OPNFV projects participating in a release. -- Upstream project documentation to be referenced -- Where there are external fora or standard development organization dependencies, list informative and normative references & specifications. - - -Committers and Contributors: ------------------------------ - -- Name of and affiliation of the project leader : - - - Christopher Price: christopher.price@ericsson.com - -- Names and affiliations of the committers - - - Christopher Price: christopher.price@ericsson.com - - Wenjing Chu (Dell): wenjing_chu@dell.com - - Ashiq Khan (NTTdocomo): khan@nttdocomo.com - - Fatih Degirmenci: fatih.degirmenci@ericsson.com - - Rodriguez, Iben: Iben.Rodriguez@spirent.com - - Malla Reddy Sama: sama@docomolab-euro.com - -- Any other contributors - - - Bryan Sullivan (AT&T) - - Trevor Cooper: trevor.cooper@intel.com - - -Description of roles in the documentation project: - -- Committers (Editors): has overall responsibility of document structure, editing, style and toolchains -- opnfvdocs contributors: individual section will have contributors who are domain experts in those areas, other contributors may simply help out working on the documentation and tools as needed. -- other projects: Committers will be responsible for maintaining documentation artifacts in project repositories. - -Planned deliverables ---------------------- - -- Project release documentation for OPNFV - - - Including collation of all release relevant project documentations - -- Establishment and maintenance of the OPNFV documentation processes and toolchains - - -Proposed Release Schedule: ---------------------------- - -- opnfvdocs will follow each OPNFV release and produce needed documentation - - - Release 1 will provide basic documentation including revision control. - - By release 2 a multi-project toolchain will be in place with processes and version control - - Iterative improvements to the processes and toolchains are expected on a release by release basis. - - - diff --git a/enable_docu_gen.rst b/enable_docu_gen.rst new file mode 100644 index 000000000..a9cd01253 --- /dev/null +++ b/enable_docu_gen.rst @@ -0,0 +1,187 @@ +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 + + diff --git a/main.rst b/main.rst new file mode 100644 index 000000000..49ac4329b --- /dev/null +++ b/main.rst @@ -0,0 +1,95 @@ +Project Name: Documentation +============================ + +- Proposed name for the project: ''opnfv documentation'' +- Proposed name for the repository: ''opnfvdocs'' +- Project Categories: Documentation + +Project description: +--------------------- + +- Produce documentation for OPNFV releases including but not limited to: + + - Release notes + - Installation guide + - User guide + + - Any relevant references and interface specifications for OPNFV projects or components. + + - Include any architecture diagrams or specifications, reference to OPNFV requirements list. + - Provide guidelines and tooling for documentation handling across all OPNFV projects + +Scope: +------- + +- Set up a structure, and a template, for document development with source control (same as source code). Leveraging upstream documentation structure and tools. +- Following as close as possible the same contribution process & tools as our source code +- Structure OPNFV documentation logically +- Develop initial set of release documents: + + - Release note + - Install guide + - User Guide + - API reference (if there is content in release 1) + - Interface specification (if there is content in release 1) + +- Provide language options for documentation where applicable: In first release English only, Wiki (via HTML scraping from Gerrit), and PDF. +- Provide tooling and processes for OPNFV projects to implement and follow for consistency + +Dependencies: +-------------- + +- All OPNFV projects participating in a release. +- Upstream project documentation to be referenced +- Where there are external fora or standard development organization dependencies, list informative and normative references & specifications. + + +Committers and Contributors: +----------------------------- + +- Name of and affiliation of the project leader : + + - Christopher Price: christopher.price@ericsson.com + +- Names and affiliations of the committers + + - Christopher Price: christopher.price@ericsson.com + - Wenjing Chu (Dell): wenjing_chu@dell.com + - Ashiq Khan (NTTdocomo): khan@nttdocomo.com + - Fatih Degirmenci: fatih.degirmenci@ericsson.com + - Rodriguez, Iben: Iben.Rodriguez@spirent.com + - Malla Reddy Sama: sama@docomolab-euro.com + +- Any other contributors + + - Bryan Sullivan (AT&T) + - Trevor Cooper: trevor.cooper@intel.com + + +Description of roles in the documentation project: + +- Committers (Editors): has overall responsibility of document structure, editing, style and toolchains +- opnfvdocs contributors: individual section will have contributors who are domain experts in those areas, other contributors may simply help out working on the documentation and tools as needed. +- other projects: Committers will be responsible for maintaining documentation artifacts in project repositories. + +Planned deliverables +--------------------- + +- Project release documentation for OPNFV + + - Including collation of all release relevant project documentations + +- Establishment and maintenance of the OPNFV documentation processes and toolchains + + +Proposed Release Schedule: +--------------------------- + +- opnfvdocs will follow each OPNFV release and produce needed documentation + + - Release 1 will provide basic documentation including revision control. + - By release 2 a multi-project toolchain will be in place with processes and version control + - Iterative improvements to the processes and toolchains are expected on a release by release basis. + + + -- cgit 1.2.3-korg