From d1f094919f1558d05f5aa72e209ad9359135bcf4 Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Tue, 25 Jul 2017 19:28:00 -0400 Subject: [DOC-57 Add vnfrqts/guidelines submodule] Change-Id: I483f12449de27a00421289438c73baa38e0fa1af Signed-off-by: Rich Bennett --- docs/conf.py | 5 +- .../onap-developer/how-to-use-docs/addendum.rst | 80 ++++++ .../how-to-use-docs/documentation-guide.rst | 122 +++++++++ .../how-to-use-docs/include-documentation.rst | 298 +++++++++++++++++++++ .../guide/onap-developer/how-to-use-docs/index.rst | 11 + docs/guide/onap-developer/index.rst | 11 + docs/guide/platform-administrator/index.rst | 12 + docs/guide/service-designer/index.rst | 12 + docs/guide/vnf-provider/index.rst | 11 + docs/how-to-use-docs/addendum.rst | 80 ------ docs/how-to-use-docs/documentation-guide.rst | 115 -------- docs/how-to-use-docs/include-documentation.rst | 298 --------------------- docs/how-to-use-docs/index.rst | 11 - docs/index.rst | 14 +- docs/release/index.rst | 21 +- docs/release/release-notes/index.rst | 28 -- docs/submodules/vnfrqts/guidelines | 1 + 17 files changed, 587 insertions(+), 543 deletions(-) create mode 100644 docs/guide/onap-developer/how-to-use-docs/addendum.rst create mode 100644 docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst create mode 100644 docs/guide/onap-developer/how-to-use-docs/include-documentation.rst create mode 100644 docs/guide/onap-developer/how-to-use-docs/index.rst create mode 100644 docs/guide/onap-developer/index.rst create mode 100644 docs/guide/platform-administrator/index.rst create mode 100644 docs/guide/service-designer/index.rst create mode 100644 docs/guide/vnf-provider/index.rst delete mode 100644 docs/how-to-use-docs/addendum.rst delete mode 100644 docs/how-to-use-docs/documentation-guide.rst delete mode 100644 docs/how-to-use-docs/include-documentation.rst delete mode 100644 docs/how-to-use-docs/index.rst delete mode 100644 docs/release/release-notes/index.rst create mode 160000 docs/submodules/vnfrqts/guidelines (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 580cce8a8..b3d753323 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -81,7 +81,10 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] +exclude_patterns = [ + '_build', + 'templates' + ] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/guide/onap-developer/how-to-use-docs/addendum.rst b/docs/guide/onap-developer/how-to-use-docs/addendum.rst new file mode 100644 index 000000000..ee0e5f24e --- /dev/null +++ b/docs/guide/onap-developer/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/guide/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst new file mode 100644 index 000000000..5dc3d714e --- /dev/null +++ b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst @@ -0,0 +1,122 @@ +.. 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 ` 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 `_ 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) + + 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 `/docs/` directory. +The documentation toolchain will look in these directories and be triggered by events in repositories +containing these directories. +when generating documents. + +.. index:: master, document + +Document Structure and Contribution +----------------------------------- +A top level master_document 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/ + ├── release + │ ├── overview + │ ├── architecture + │ ├── use-cases + │ ├── tutorials + │ └── release-notes + ├── onap-developer + │ ├── design + │ ├── develop + │ ├── document + │ └── test + ├── administrator + │ ├── configure + │ ├── deploy + │ └── operate + ├── 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 repository and reference content as needed +from other project repository. +To provide content for these other projects place .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**: `/docs/xxxxxxxx` + +- Additional descriptions for the above outline as it is finalized. + + diff --git a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst new file mode 100644 index 000000000..8fa689fe4 --- /dev/null +++ b/docs/guide/onap-developer/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 /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://@gerrit.onap.org:29418/doc + cp -p doc/docs/templates/release-notes /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://@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//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 +`_. + +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 ` + +.. 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 `_ 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 + + +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 / + +Move the static files to your project folder: + +.. code-block:: bash + + mv docs/_static/ / + +Build the documentation from within your project folder: + +.. code-block:: bash + + sphinx-build -b html + +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 `/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/guide/onap-developer/how-to-use-docs/index.rst b/docs/guide/onap-developer/how-to-use-docs/index.rst new file mode 100644 index 000000000..f2ec27587 --- /dev/null +++ b/docs/guide/onap-developer/how-to-use-docs/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Documentation +============= + +.. toctree:: + :maxdepth: 2 + + documentation-guide + include-documentation + addendum diff --git a/docs/guide/onap-developer/index.rst b/docs/guide/onap-developer/index.rst new file mode 100644 index 000000000..a6a5d2223 --- /dev/null +++ b/docs/guide/onap-developer/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _onap_developer_guide: + +ONAP Developer Guide +==================== + +.. toctree:: + :maxdepth: 1 + + how-to-use-docs/index diff --git a/docs/guide/platform-administrator/index.rst b/docs/guide/platform-administrator/index.rst new file mode 100644 index 000000000..7215c72be --- /dev/null +++ b/docs/guide/platform-administrator/index.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _service_designer_guide: + +Service Designer Guide +====================== + +.. toctree:: + :maxdepth: 2 + +More to be added +---------------- diff --git a/docs/guide/service-designer/index.rst b/docs/guide/service-designer/index.rst new file mode 100644 index 000000000..b87254460 --- /dev/null +++ b/docs/guide/service-designer/index.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _administrator_guide: + +Admistrator Guide +================= + +.. toctree:: + :maxdepth: 2 + +More to be added +---------------- diff --git a/docs/guide/vnf-provider/index.rst b/docs/guide/vnf-provider/index.rst new file mode 100644 index 000000000..cad3b7aa9 --- /dev/null +++ b/docs/guide/vnf-provider/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _vnf_provider_guide: + +VNF Provider Guide +================== + +.. toctree:: + :maxdepth: 2 + + ../../submodules/vnfrqts/guidelines/docs/index.rst diff --git a/docs/how-to-use-docs/addendum.rst b/docs/how-to-use-docs/addendum.rst deleted file mode 100644 index ee0e5f24e..000000000 --- a/docs/how-to-use-docs/addendum.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. 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 deleted file mode 100644 index d51922939..000000000 --- a/docs/how-to-use-docs/documentation-guide.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. 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 ` 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 `_ 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) - - 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 `/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 repository and reference content as needed -from other project repository. -To provide content for these other projects place .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**: `/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 deleted file mode 100644 index 8fa689fe4..000000000 --- a/docs/how-to-use-docs/include-documentation.rst +++ /dev/null @@ -1,298 +0,0 @@ -.. 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 /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://@gerrit.onap.org:29418/doc - cp -p doc/docs/templates/release-notes /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://@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//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 -`_. - -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 ` - -.. 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 `_ 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 - - -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 / - -Move the static files to your project folder: - -.. code-block:: bash - - mv docs/_static/ / - -Build the documentation from within your project folder: - -.. code-block:: bash - - sphinx-build -b html - -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 `/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 deleted file mode 100644 index df3b64247..000000000 --- a/docs/how-to-use-docs/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. 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 index 83f8b8a81..ca298c119 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,20 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -Welcome to ONAP documentation! -================================ +.. _master_index: -Contents: +ONAP Documentation +================== .. toctree:: :maxdepth: 1 release/index - how-to-use-docs/index + guide/onap-developer/index + guide/service-designer/index + guide/platform-administrator/index + guide/vnf-provider/index + + Indices and tables ================== @@ -17,4 +22,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/release/index.rst b/docs/release/index.rst index d73b25e8f..bfd896f7c 100644 --- a/docs/release/index.rst +++ b/docs/release/index.rst @@ -4,18 +4,29 @@ Release ======= -Summary -======= - Overview of use cases, installation, release notes, etc. +Architecture +------------ + + +Use Cases +--------- + + +Tutorials +--------- + + +Release Notes +------------- -Contents: +Component Specific Notes +++++++++++++++++++++++++ .. toctree:: :maxdepth: 1 - release-notes/index.rst diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst deleted file mode 100644 index 337469c1a..000000000 --- a/docs/release/release-notes/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. 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 `_ 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/submodules/vnfrqts/guidelines b/docs/submodules/vnfrqts/guidelines new file mode 160000 index 000000000..0ac8f5220 --- /dev/null +++ b/docs/submodules/vnfrqts/guidelines @@ -0,0 +1 @@ +Subproject commit 0ac8f52204d571ccd5a98af0e211bd138ceac846 -- cgit 1.2.3-korg