summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorVictor Laza <vlaza@cloudbasesolutions.com>2015-04-15 22:42:27 +0300
committerVictor Laza <vlaza@cloudbasesolutions.com>2015-04-15 22:42:27 +0300
commit131605f80924c2e1cd49c1797661f84362dc1a84 (patch)
treeb7a49097f94c2ba95d97e5efa2bd289c56d3fc0d /docs
parente2155e6f266e1c9af5d3e4dc625cd2d4adf4de79 (diff)
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 <vlaza@cloudbasesolutions.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/enable_docu_gen.rst187
-rw-r--r--docs/main.rst95
2 files changed, 282 insertions, 0 deletions
diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst
new file mode 100644
index 000000000..a9cd01253
--- /dev/null
+++ b/docs/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://<username>@gerrit.opnfv.org:29418/<project>
+
+
+**Inside the repository create the following structure:**
+ gerrit.opnfv.org/<project> - 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://<username>@gerrit.opnfv.org:29418/releng
+
+cd releng/jjb/<project>/
+
+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 <project>.yml and make sure you have the job-templates set as in the example below:
+
+
+``- job-template:
+ name: 'opnfvdocs-daily-{stream}'
+ <more code present>
+ 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'
+ <more code present>
+ builders:
+ - shell:
+ !include-raw build-docu.sh
+
+
+
+- job-template:
+ name: 'opnfvdocs-merge'
+ <more code present>
+ 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 <project>.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/docs/main.rst b/docs/main.rst
new file mode 100644
index 000000000..49ac4329b
--- /dev/null
+++ b/docs/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.
+
+
+