summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRich Bennett <rb2745@att.com>2017-07-19 01:36:52 -0400
committerSteven Wright <sw3588@att.com>2017-07-19 17:27:36 +0000
commitac93e0eb246a03c02df7a6b7704aaabfdb7461f0 (patch)
tree493829a3846cacccd492ca30afb6fc6733d47ce7
parentfa0b21e328c982a35de41c5d25127452751a3e6d (diff)
[DOC-23]Initial structure and Documentation Guide
Change-Id: Ie0fdb7be60acd79b878c2d9b985aaaf6aca035d2 Signed-off-by: Rich Bennett <rb2745@att.com>
-rw-r--r--.gitreview4
-rw-r--r--docs/how-to-use-docs/addendum.rst80
-rw-r--r--docs/how-to-use-docs/documentation-guide.rst115
-rw-r--r--docs/how-to-use-docs/include-documentation.rst298
-rw-r--r--docs/how-to-use-docs/index.rst11
-rw-r--r--docs/index.rst20
-rw-r--r--docs/release/index.rst21
-rw-r--r--docs/release/release-notes/index.rst28
-rw-r--r--docs/templates/release/release-notes/index.rst11
-rw-r--r--docs/templates/release/release-notes/release-notes.rst27
10 files changed, 615 insertions, 0 deletions
diff --git a/.gitreview b/.gitreview
new file mode 100644
index 000000000..c088dd69b
--- /dev/null
+++ b/.gitreview
@@ -0,0 +1,4 @@
+[gerrit]
+host=gerrit.onap.org
+port=29418
+project=doc.git
diff --git a/docs/how-to-use-docs/addendum.rst b/docs/how-to-use-docs/addendum.rst
new file mode 100644
index 000000000..ee0e5f24e
--- /dev/null
+++ b/docs/how-to-use-docs/addendum.rst
@@ -0,0 +1,80 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Addendum
+========
+
+Index File
+==========
+
+The index file must relatively reference your other rst files in that directory.
+
+Here is an example index.rst :
+
+.. code-block:: bash
+
+ *******************
+ Documentation Title
+ *******************
+
+ .. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ documentation-example
+
+Source Files
+============
+
+Document source files have to be written in reStructuredText format (rst).
+Each file would be build as an html page.
+
+Here is an example source rst file :
+
+.. code-block:: bash
+
+ =============
+ Chapter Title
+ =============
+
+ Section Title
+ =============
+
+ Subsection Title
+ ----------------
+
+ Hello!
+
+Writing RST Markdown
+====================
+
+See http://sphinx-doc.org/rest.html .
+
+**Hint:**
+You can add html content that only appears in html output by using the
+'only' directive with build type
+('html' and 'singlehtml') for an ONAP document. But, this is not encouraged.
+
+.. code-block:: bash
+
+ .. only:: html
+ This line will be shown only in html version.
+
+Verify Job
+----------
+
+The verify job name is **docs-verify-rtd-{branch}**.
+
+When you send document changes to gerrit, jenkins will create your documents
+in HTML formats (normal and single-page) to verify that new document can be
+built successfully. Please check the jenkins log and artifact carefully.
+You can improve your document even if the build job succeeded.
+
+Merge Job
+----------
+
+The merge job name is **docs-merge-rtd-{branch}**.
+
+Once the patch is merged, jenkins will automatically trigger building of
+the new documentation. This might take about 15 minutes while readthedocs
+builds the documentatation. The newly built documentation shall show up
+as appropriate placed in docs.onap.org/{branch}/path-to-file.
diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst
new file mode 100644
index 000000000..d51922939
--- /dev/null
+++ b/docs/how-to-use-docs/documentation-guide.rst
@@ -0,0 +1,115 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Documentation Guide
+===================
+
+This page describes how documentation is created for the Open Network Automation Platform (ONAP).
+ONAP projects create a variety of document types depending on the nature of the project.
+Some projects will create detailed technical descriptions such as configuration parameters or how to
+use or extend the functionality of platform component that may be used as a standalone reference for that project and/or
+be used in larger end to end documents tailored to a specific user audience and task they are performing.
+
+Acknowledgement
+---------------
+
+Much of the content in this document is derived from similar documentation processes used in other Linux Foundation Projects
+including OPNFV and Open Daylight.
+
+.. contents::
+ :depth: 3
+ :local:
+
+Getting Started
+---------------
+ONAP documentation is stored in git repositories, changes are managed with gerrit reviews, and published documents
+automatically generated when there is a change in any source used to build the documentation.
+
+Authors create source for documents in reStructured Text (RST) that is automatically rendered to HTML and PDF
+and published on Readthedocs.io.
+The developer WiKi can reference these rendered documents directly allowing projects to
+easily maintain current release documentation.
+Read :ref:`this page <include-documentation>` which describes how documentation is created from
+ONAP Documentation project (doc) documentation source and other ONAP projects providing source material.
+
+Licencing Your Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All contributions to the ONAP project are done in accordance with the ONAP licensing requirements.
+Documentation in ONAP is contributed
+in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
+All documentation files need to be licensed using the text below. The license may be applied in the first lines of
+all contributed RST files:
+
+.. code-block:: bash
+
+ .. This work is licensed under a Creative Commons Attribution 4.0 International License.
+ .. (c) <optionally add copywriters name>
+
+ These lines will not be rendered in the html and pdf files.
+
+Storing Content Files in Your Repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory.
+The documentation toolchain will look in these directories and be triggered by events in repositories
+containing these directories.
+when generating documents.
+
+Document Structure and Contribution
+-----------------------------------
+A top level structure is proposed for organizing and storing all documents.
+Four areas as shown below with some additional detail under each area.
+This structure may change some as we get the full requirements and gain experience with the first reelase of ONAP.
+Where multiple sections with similar content are expected, templates can be created and stored
+under `doc/docs/templates/`. For example each component providing release notes uses the same release-note template.
+A template is a directory name in `doc/docs/templates` and the directory contains at least an index.rst file with
+content and as needed references to other sources in the template directory.
+
+Project teams are encouraged to reuse and if needed propose new templates to ensure that there is
+consistency across projects.
+
+::
+
+ docs/
+ ├── onap-developer
+ │ ├── architecture
+ │ ├── develop
+ │ ├── test
+ │ └── tutorial
+ ├── release
+ │ ├── configure
+ │ ├── install
+ │ ├── overview
+ │ └── release-notes
+ ├── service-designer
+ │ ├── deploy
+ │ ├── design
+ │ └── portal
+ └── vnf-provider
+ ├── guidelines
+ └── sdk
+
+
+Release Documentation
+^^^^^^^^^^^^^^^^^^^^^
+Release documentation is the set of documents that are published for each ONAP release.
+The documents have a master index.rst file in the <doc> repository and reference content as needed
+from other project repository.
+To provide content for these other projects place <content>.rst files in a directory in your repository that
+matches the master document and add a reference to that file in the correct place in the
+corresponding master index.rst.
+
+**Release Overview**: `doc/docs/release/overview`
+
+- Content for this is prepared by the Marketing team together with the use case committee and doc project team.
+- This document is not a project contribution driven document.
+
+**Installation Instruction**: `doc/docs/release/install`
+
+- Document providing an introduction, order, and aggregation of release notes from other component projects.
+- This document is a contribution driven document.
+
+**To Be Provided**: `<repo>/docs/xxxxxxxx`
+
+- Additional descriptions for the above outline as it is finalized.
+
+
diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst
new file mode 100644
index 000000000..8fa689fe4
--- /dev/null
+++ b/docs/how-to-use-docs/include-documentation.rst
@@ -0,0 +1,298 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _include-documentation:
+
+============================
+Including your Documentation
+============================
+
+.. contents::
+ :depth: 3
+ :local:
+
+In your project repository
+--------------------------
+
+Add your documentation to your repository in the folder structure and
+using templates as described above. The documentation templates
+are available in `doc/docs/templates/`, you should
+copy the relevant templates to your <repo>/docs/ directory in your repository.
+For instance if you want to document release-notes, then your steps shall be
+as follows:
+
+.. code-block:: bash
+
+ git clone ssh://<your_id>@gerrit.onap.org:29418/doc
+ cp -p doc/docs/templates/release-notes <your_repo>/docs/release-notes/
+
+
+You should then add the relevant information to the template that will
+explain the documentation. When you are done writing, you can commit
+the documentation to the your project repository.
+
+.. code-block:: bash
+
+ git add .
+ git commit --signoff --all
+ git review
+
+In the ONAP doc Repository
+--------------------------
+
+To import project documents from project repositories, we use git submodules.
+Each ONAP project providing documentation, other than the doc project, is loaded under `doc/docs/submodules/`
+when needed for validating or publishing documentation. To describe the relationship between content files
+we use the `Sphinx toctree directive`.
+
+The following diagram illustrates:
+ - all ONAP gerrit project repositories,
+ - the doc project repository including a main index.rst,
+ - other master document directories and/or RST files that may be created to organize sections and documents,
+ - the submodules directory where other repositories and directories/files may be referenced,
+ - the templates directory with one example, a release-notes template, and
+ - another project repository `appc` that provides documentation source by copying and filling in an instance of the release-notes template.
+
+
+.. graphviz::
+
+
+ digraph docstructure {
+ size="8,12";
+ node [fontname = "helvetica"];
+ // Align gerrit repos and docs directories
+ {rank=same doc aaf aai appc repoelipse vnfsdk vvp}
+ {rank=same releasenotestemplate localappcdocs }
+
+ //Show submodule linkage to docs directory
+ submodules -> localappcdocs [style=dotted];
+
+ //Illustrate Gerrit Repos and provide URL/Link for complete repo list
+ gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ];
+ gerrit -> doc;
+ gerrit -> aaf;
+ gerrit -> aai;
+ gerrit -> appc;
+ gerrit -> repoelipse; repoelipse [label=". . . ."];
+ gerrit -> vnfsdk;
+ gerrit -> vvp;
+
+ //Show example of local appc instance release notes
+ appc -> localappcdocs; localappcdocs [label="docs"];
+ localappcdocs -> releasenotesinstance; releasenotesinstance [label="release-notes"];
+ releasenotesinstance -> relnoteindexinstance; relnoteindexinstance [label="index.rst", shape=box];
+ releasenotesinstance -> relnoteotherinstance; relnoteotherinstance [label="... other sections", shape=box];
+
+ //Show detail structure of a portion of doc/docs _images _static _templates multiple master documents omitted
+ doc -> docs;
+ docs -> confpy; confpy [label="conf.py",shape=box];
+ docs -> toplevelindex; toplevelindex [label="index.rst", shape=box];
+ docs -> release;
+ docs -> rsttemplates; rsttemplates [label="templates"];
+ docs -> indexdirelipse; indexdirelipse [label="...other\ndocuments"];
+ docs -> submodules
+
+ //Example Release notes document
+ release -> releasenotes; releasenotes [label="release-notes"];
+ releasenotes -> lowerlevelindex; lowerlevelindex [label="index.rst", shape=box];
+
+ //Example release-notes template
+ rsttemplates -> releasenotestemplate; releasenotestemplate [label="release-notes"];
+ releasenotestemplate -> relnoteindex; relnoteindex [label="index.rst", shape=box];
+ releasenotestemplate -> relnoteother; relnoteother [label="... other sections", shape=box];
+ }
+
+In the toctree
+++++++++++++++
+
+To include your project specific documentation in the composite documentation,
+first identify where your project documentation should be included.
+Say your project provides release-notes and should be referenced in the `doc/docs/release/release-notes/index.rst toctree`, then:
+
+.. code-block:: bash
+
+ git clone ssh://<your_id>@gerrit.onap.org:29418/doc
+ vim doc/docs/release/release-notes/index.rst
+
+This opens the text editor. Identify where you want to add your release notes.
+If your release notes are to be added to the toctree, simply include the path to
+it, example:
+
+
+.. code-block:: bash
+
+ .. toctree::
+ :maxdepth: 1
+
+ ../../submodules/<your_repo>/docs/release-notes/index
+
+When finished, you can request a commit to the doc project repository.
+Be sure to add the project leader of the docs project as a reviewr of the change you just pushed in gerrit.
+
+.. code-block:: bash
+
+ git add .
+ git commit --signoff --all
+ git review
+
+
+As a Hyperlink
+++++++++++++++
+
+It's pretty common to want to reference another location in the
+ONAP documentation and it's pretty easy to do with
+reStructuredText. This is a quick primer, more information is in the
+`Sphinx section on Cross-referencing arbitrary locations
+<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
+
+Within a single document, you can reference another section simply by::
+
+ This is a reference to `The title of a section`_
+
+Assuming that somewhere else in the same file there a is a section
+title something like::
+
+ The title of a section
+ ^^^^^^^^^^^^^^^^^^^^^^
+
+It's typically better to use ``:ref:`` syntax and labels to provide
+links as they work across files and are resilient to sections being
+renamed. First, you need to create a label something like::
+
+ .. _a-label:
+
+ The title of a section
+ ^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: The underscore (_) before the label is required.
+
+Then you can reference the section anywhere by simply doing::
+
+ This is a reference to :ref:`a-label`
+
+or::
+
+ This is a reference to :ref:`a section I really liked <a-label>`
+
+.. note:: When using ``:ref:``-style links, you don't need a trailing
+ underscore (_).
+
+Because the labels have to be unique, it usually makes sense to prefix
+the labels with the project name to help share the label space, e.g.,
+``sfc-user-guide`` instead of just ``user-guide``.
+
+
+'doc8' Validation
+-----------------
+It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
+To validate your rst files using doc8, install doc8.
+
+.. code-block:: bash
+
+ sudo pip install doc8
+
+doc8 can now be used to check the rst files. Execute as,
+
+.. code-block:: bash
+
+ doc8 --ignore D000,D001 <file>
+
+
+Testing: Build Documentation Locally
+------------------------------------
+
+Composite DOC documentation
++++++++++++++++++++++++++++++++++
+To build the whole documentation under doc/, follow these steps:
+
+Install virtual environment.
+
+.. code-block:: bash
+
+ sudo pip install virtualenv
+ cd /local/repo/path/to/project
+
+Download the DOC repository.
+
+.. code-block:: bash
+
+ git clone http://gerrit.onap.org/r/doc
+
+Change directory to docs & install requirements.
+
+.. code-block:: bash
+
+ cd doc
+ sudo pip install -r etc/requirements.txt
+
+Update submodules, build documentation using tox & then open using any browser.
+
+.. code-block:: bash
+
+ cd doc
+ git submodule update --init
+ tox -edocs
+ firefox docs/_build/html/index.html
+
+.. note:: Make sure to run `tox -edocs` and not just `tox`.
+
+Individual project documentation
+++++++++++++++++++++++++++++++++
+To test how the documentation renders in HTML, follow these steps:
+
+Install virtual environment.
+
+.. code-block:: bash
+
+ sudo pip install virtualenv
+ cd /local/repo/path/to/project
+
+Download the doc repository.
+
+.. code-block:: bash
+
+ git clone http://gerrit.onap.org/r/doc
+
+Change directory to doc & install requirements.
+
+.. code-block:: bash
+
+ cd doc
+ sudo pip install -r etc/requirements.txt
+
+Move the conf.py file to your project folder where RST files have been kept:
+
+.. code-block:: bash
+
+ mv doc/docs/conf.py <path-to-your-folder>/
+
+Move the static files to your project folder:
+
+.. code-block:: bash
+
+ mv docs/_static/ <path-to-your-folder>/
+
+Build the documentation from within your project folder:
+
+.. code-block:: bash
+
+ sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
+
+Your documentation shall be built as HTML inside the
+specified output folder directory.
+
+.. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
+
+
+Adding your project repository as a submodule
+---------------------------------------------
+
+Clone the doc repository and add your submodule using the commands below and where $reponame is your repository name.
+
+.. code-block:: bash
+
+ cd docs/submodules/
+ git submodule git https://gerrit.onap.org/r/$reponame
+ git submodule init $reponame/
+ git submodule update $reponame/
+ git add .
+ git review
diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst
new file mode 100644
index 000000000..df3b64247
--- /dev/null
+++ b/docs/how-to-use-docs/index.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Documentation Guide
+===================
+
+.. toctree::
+ :maxdepth: 2
+
+ documentation-guide
+ include-documentation
+ addendum
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 000000000..83f8b8a81
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,20 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Welcome to ONAP documentation!
+================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 1
+
+ release/index
+ how-to-use-docs/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/docs/release/index.rst b/docs/release/index.rst
new file mode 100644
index 000000000..d73b25e8f
--- /dev/null
+++ b/docs/release/index.rst
@@ -0,0 +1,21 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Release
+=======
+
+Summary
+=======
+
+Overview of use cases, installation, release notes, etc.
+
+
+
+
+
+Contents:
+
+.. toctree::
+ :maxdepth: 1
+
+ release-notes/index.rst
diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst
new file mode 100644
index 000000000..337469c1a
--- /dev/null
+++ b/docs/release/release-notes/index.rst
@@ -0,0 +1,28 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+==============
+Release Notes
+==============
+
+Release notes as provided by the ONAP project documents are captured in this section.
+These include details of software versions used, known limitations and outstanding trouble
+reports.
+
+Summary
+-------
+OpenECOMP 1.0.0 represents a complete demo platform with two
+service examples as contributed by AT&T to the Linux Foundation ONAP project.
+
+Installation Instructions
+-------------------------
+
+BasicOpenECOMP installation instructions are available as a `README.md <https://nexus.openecomp.org/content/sites/raw/org.openecomp.demo/heat/1.0.0-SNAPSHOT/README.md>`_ file. Step by step tutorials for setting up a Rackspace account, using the portal, designing services, and instantiating services are provided here.
+
+
+Components
+----------
+
+.. toctree::
+ :maxdepth: 1
+
+
diff --git a/docs/templates/release/release-notes/index.rst b/docs/templates/release/release-notes/index.rst
new file mode 100644
index 000000000..e703944ef
--- /dev/null
+++ b/docs/templates/release/release-notes/index.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+****************************
+<Project Name> Release Notes
+****************************
+
+.. toctree::
+ :maxdepth: 1
+
+ release-notes
diff --git a/docs/templates/release/release-notes/release-notes.rst b/docs/templates/release/release-notes/release-notes.rst
new file mode 100644
index 000000000..002463d86
--- /dev/null
+++ b/docs/templates/release/release-notes/release-notes.rst
@@ -0,0 +1,27 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+This document provides the release notes for <RELEASE> of <COMPONENT>.
+
+.. contents::
+ :depth: 3
+ :local:
+
+
+
+Important notes
+===============
+
+<STATE IMPORTANT NOTES/DEVIATIONS SINCE PREVIOUS ITERATIVE RELEASE AND OTHER IMPORTANT NOTES FOR THIS RELEASE>
+
+<EXAMPLE>:
+
+
+
+Summary
+=======
+
+<SUMMARIZE THE RELEASE - THE CONTENT - AND OTHER IMPORTANT HIGH LEVEL PROPERTIES>
+
+<EXAMPLE>:
+