diff options
Diffstat (limited to 'docs/guide/onap-developer/how-to-use-docs')
4 files changed, 222 insertions, 188 deletions
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 index 380b05cce..6bce35df9 100644 --- a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst +++ b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst @@ -1,65 +1,46 @@ .. 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. -These descriptions may be together as a reference for that project and/or -be used in 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 +Introduction +============ +This guide describes how to create documentation 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. +These descriptions may be used together as a reference for that project +and/or be used in documents tailored to a specific user audience and +task they are performing. + +Much of the content in this document is derived from similar +documentation processes used in other Linux Foundation +Projects including OPNFV and Open Daylight. + + +End to End View --------------- -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> +ONAP documentation is stored in git repositories, changes are managed +with gerrit reviews, and published documents generated when there is a +change in any source used to build the documentation. - These lines will not be rendered in the html and pdf files. +Authors create source for documents in reStructured Text (RST) that is +rendered to HTML and PDF and published on Readthedocs.io. +The developer Wiki or other web sites can reference these rendered +documents directly allowing projects to easily maintain current release +documentation. -Storing Content Files in Your Repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory. -The documentation tool chain will look in these directories when triggered by verify and merge events. -.. index:: master, document +Structure +--------- +A top level master_document structure is used to organize all +documents for an ONAP release that reside in the doc git repository. +Complete documents or guides may reside here and reference parts of +source for documentation from other project repositories +A starting structure is shown below and may change as content is +intergrated for each release. Others ONAP projects will provide +content that is referenced from this structure. -Document Structure and Contribution ------------------------------------ -A top level master_document structure is proposed for organizing all documents -in the four areas as shown below with additional detail under each area. -This structure may change as we gain experience with the first release of ONAP. +.. index:: master :: @@ -88,29 +69,48 @@ This structure may change as we gain experience with the first release of ONAP. ├── guidelines └── sdk + + +Source Files +------------ +All documentation for a project should be structured and stored +in or below `<your_project_repo>/docs/` directory as Restructured Text. +ONAP jenkins jobs that verify and merge documentation are triggered by +file changes in the docs directory and below. + + +.. index:: licensing + +Licencing +--------- +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 copyrights company name> + + These lines will not be rendered in the html and pdf files. + + + Templates -^^^^^^^^^ -Where multiple sections with similar content are expected, templates can be created and stored -under `doc/docs/templates/` and used a starting point for similar content. -For example the high level architecture and interface information for an ONAP component. -A template is a directory name in `doc/docs/templates` , the directory contains at least an -index.rst file with a starting point for creating content, and as needed -references to other sources in the template directory. Current templates are shown below. +--------- +To encourage consistency of information across components, some +templates are available as a starting point under `doc/docs/templates/` +and listed below. With the "show source" feature on html pages, you +may be able to use portions of an existing page as starting point for +creating new content. + .. toctree:: :maxdepth: 1 - - ../../../templates/index - -Project teams are encouraged to reuse and propose new templates for reuse. - -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. + :glob: + ../../../templates/**/index + 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 index 3471ac1ec..7b2818c6a 100644 --- a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst +++ b/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst @@ -1,60 +1,116 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _include-documentation: -============================ -Including your Documentation -============================ - -.. contents:: - :depth: 3 - :local: +Setting Up +========== +Some initial steps are required to connect a project with +the master document structure and enable automated publishing of +changes as summarized in the following diagram and described detail +below. + +.. seqdiag:: + + seqdiag { + RD [label = "Read The Docs", color =lightgreen ]; + DA [label = "Doc Project\nAuthor/Committer", color=lightblue]; + DR [label = "Doc Gerrit Repo" , color=pink]; + PR [label = "Other Project\nGerrit Repo", color=pink ]; + PA [label = "Other Project\nAuthor/Committer", color=lightblue]; + + === One time setup doc project only === + RD -> DA [label = "Account Setup" ]; + DA -> DR [label = "Create initial\nrepository content"]; + DA <<-- DR [label = "Merged" ]; + RD <-- DA [label = "Connect gerrit.onap.org" ]; + === For each project & repository containing document source === + DA -> PR [label = "Other Project Contribution to Setup\ndocs directory, index, other initial content" ]; + PR <-- PA [label = "Review/Merge Change" ]; + DA <-- PR [label = "Change Merged" ]; + DA -> DR [label = "Add Other Project Repo as\nGit submodule in doc project" ]; + DA <-- DR [label = "Change Merged" ]; + } + + + +Setup doc project +----------------- +These steps are performed only once for the doc project and include: -In your project repository --------------------------- +(1) creating in the doc repository an initial: + - sphinx master document index + - directory structure aligned with the document structure + - set of test performed in jenkins verify jobs + - configuration for sphinx plugins and redendering of content + +(2) establishing an account at readthedocs connected with gerrit.onap.org -Add your documentation to your repository in the folder structure and -using templates as described above. -When using a template, copy the directory in `doc/docs/templates/`, -to your <repo>/docs/ directory in your repository. -For instance if you want to document component-info, then your steps shall be -as follows: -.. code-block:: bash +Setup other project(s) +---------------------- +These steps are performed for each new project repo (referred to in the +next three code blocks as $newreponame) the master document +in doc repository references and include: - git clone ssh://<your_id>@gerrit.onap.org:29418/doc - cp -p doc/docs/templates/component-info <your_repo>/docs/component-info/ +(1) clone, modify, and commit to the other project an initial: docs top +level directory; index.rst; any other intial content. +.. code-block:: bash -You should then add the relevant information to the template. -When you are done writing, you can commit -the documentation to the your project repository. -The sequence below shows basic git/gerrit steps, -see `Developer Best Practices`_ for complete current information. + git clone ssh://<your_id>@gerrit.onap.org:29418/$newreponame + cd $newreponame + mkdir docs + echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _Developer Best Practices: https://wiki.onap.org/x/BZZk + $newreponame + ============ + .. toctree:: + :maxdepth: 1 + + " > docs/index.rst + + git add . + git commit -m "Add RST docs directory and index" -s + git commit --amend + # modify the commit message to comply with ONAP best practices + git review + +When the above commit is reviewed and merged complete step 2 before any +new changes are merged into $newreponame. + +(2) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the other project and initialized as a git submodule. + .. code-block:: bash + git clone ssh://<your_id>@gerrit.onap.org:29418/doc + # For top level repositories use the following + mkdir doc/docs/submodules/$reponame + # For lower level repositories you may need to make a directory for each node in path + + echo "../submodules/$newreponame/index.rst" >> docs/release/index.rst + cd doc/docs/submodules/$reponame + + git submodule git https://gerrit.onap.org/r/$reponame + git submodule init $reponame/ + git submodule update $reponame/ + + git add . - git commit --signoff --all + git commit -m "Add $newreponame as asubmodule" -s + git commit --amend + # modify the commit message to comply with ONAP best practices 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 diagram below illustrates what is accomplished in the setup steps +above from the perspective of a file structure created for local test, +jenkins verify job, and/or merge/publish documentation including: -The following diagram illustrates: - all ONAP gerrit project repositories, - - the doc project repository including a master document index.rst, - - other document directories and/or RST files that organize sections and documents doc repository, - - the submodules directory where other project repositories and directories/files may be referenced, - - the templates directory with one example, a component-info template that may referenced in release orhigh level design documents, and - - another project repository example, `appc` that provides documentation source by copying and filling in an instance of the component-info template. + - the doc project repository including a master document index.rst, templates, configuration + - the submodules directory where other project repositories and directories/files may be referenced + - newreponame project repository being added and integrated. .. graphviz:: @@ -64,81 +120,54 @@ The following diagram illustrates: size="8,12"; node [fontname = "helvetica"]; // Align gerrit repos and docs directories - {rank=same doc aaf aai appc repoelipse vnfsdk vvp} - {rank=same componentinfotemplate localappcdocs } + {rank=same doc aaf aai newreponame repoelipse vnfsdk vvp} + {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} - //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 -> newreponame; + gerrit -> repoelipse; + repoelipse [label=". . . ."]; gerrit -> vnfsdk; gerrit -> vvp; - //Show example of local appc instance of component info - appc -> localappcdocs; localappcdocs [label="docs"]; - localappcdocs -> componentinfoinstance; componentinfoinstance [label="component-info"]; - componentinfoinstance -> compinfoindexinstance; compinfoindexinstance [label="index.rst", shape=box]; - componentinfoinstance -> compinofotherinstance; compinofotherinstance [label="... other sections", shape=box]; + //Show example of local newreponame instance of component info + newreponame -> newreponamedocsdir; + newreponamesm -> newreponamedocsdir; + newreponamedocsdir [label="docs"]; + newreponamedocsdir -> newrepodocsdirindex; + newrepodocsdirindex [label="index.rst", shape=box]; - //Show detail structure of a portion of doc/docs _images _static _templates multiple master documents omitted + //Show detail structure of a portion of doc/docs doc -> docs; - docs -> confpy; confpy [label="conf.py",shape=box]; - docs -> toplevelindex; toplevelindex [label="index.rst", shape=box]; + docs -> confpy; + confpy [label="conf.py",shape=box]; + docs -> masterindex; + masterindex [label="Master index.rst", shape=box]; docs -> release; - docs -> rsttemplates; rsttemplates [label="templates"]; - docs -> indexdirelipse; indexdirelipse [label="...other\ndocuments"]; + docs -> templates; + docs -> otherdocdocumentelipse; + otherdocdocumentelipse [label="...other\ndocuments"]; docs -> submodules - - //Example Release document, section release notes, and reference to an instance of component-info - release -> releasenotes; releasenotes [label="release-notes"]; - releasenotes -> lowerlevelindex; lowerlevelindex [label="index.rst", shape=box]; - lowerlevelindex -> componentinfoinstance; - - //Example component-info template - rsttemplates -> componentinfotemplate; componentinfotemplate [label="component-info"]; - componentinfotemplate -> compinfotmpindex; compinfotmpindex [label="index.rst", shape=box]; - componentinfotemplate -> compinfotmpother; compinfotmpother [label="... other sections", shape=box]; + + masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"]; + + //Show submodule linkage to docs directory + submodules -> newreponamesm [style=dotted,label="git\nsubmodule\nreference"]; + newreponamesm [label="newreponame"]; + + //Example Release document index that references component info provided in other project repo + release -> releasedocumentindex; + releasedocumentindex [label="index.rst", shape=box]; + releasedocumentindex -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"]; + } -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 component-info and should be referenced in the `doc/docs/release/release-info/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/component-info/index - -When finished, you can request a commit to the doc project repository. -Be sure to add the PTL of the docs project as a reviewer of the change you just -pushed in gerrit. - -.. code-block:: bash - - git add . - git commit --signoff --all - git review +THE FOLLOWING SECTION NEEDS TO BE CONSOLIDATED / UPDATED As a Hyperlink @@ -302,3 +331,5 @@ Clone the doc repository and add your submodule using the commands below and whe 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 index f6653e9d1..48d5aa918 100644 --- a/docs/guide/onap-developer/how-to-use-docs/index.rst +++ b/docs/guide/onap-developer/how-to-use-docs/index.rst @@ -1,10 +1,11 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. This work is licensed under a + Creative Commons Attribution 4.0 International License. -Documentation -============= +Creating Documentation +====================== .. toctree:: - :maxdepth: 3 + :maxdepth: 2 documentation-guide style-guide diff --git a/docs/guide/onap-developer/how-to-use-docs/style-guide.rst b/docs/guide/onap-developer/how-to-use-docs/style-guide.rst index 8f9369b17..5d477a99b 100644 --- a/docs/guide/onap-developer/how-to-use-docs/style-guide.rst +++ b/docs/guide/onap-developer/how-to-use-docs/style-guide.rst @@ -6,34 +6,34 @@ Style guide This style guide is for ONAP documentation contributors, reviewers and committers. Getting started -=============== +--------------- When is documentation required? -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All ONAP project contributions should have corresponding documentation. This includes all new features and changes to features that impact users. How do I create ONAP documentation? ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ONAP documentation is written in ReStructuredText_ (an easy-to-read, what-you-see-is-what-you-get, plain text markup syntax). The process for creating ONAP documentation and what documents are required are described here: <<add links to Documentation process/automated tools sections>> .. _ReStructuredText: http://docutils.sourceforge.net/rst.html ReStructuredText markup conventions ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For detailed information ReStructuredText and how to best use the format, see: - `ReStructured Text Primer <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>` - `ReStructured Text Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>` Writing guidelines -================== +------------------ Following these writing guidelines will keep ONAP documentation consistent and readable. Only a few areas are covered below, as we don't want to make it too complex. Try to keep things simple and clear, and you can't go far wrong. Don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to this guide than no information at all. ONAP’s Documentation project team will be happy to help you with the prose. General guidelines for all documents ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Use standard American English and spelling - Use consistent terminology - Write in the active voice, using present simple tense when possible @@ -42,13 +42,14 @@ General guidelines for all documents - Use a spell checker Abbreviations and acronyms --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Write out the term the first time it appears in the document, immediately followed by the acronym or abbreviation in parenthesis. Then use the acronym in the rest of the document. In diagrams, if space allows, write out the full term. - Use “an” before an acronym that begins with a vowel sound when spoken aloud; use "a" before an acronym that begins with a consonant sound when spoken aloud. -+ Examples: an MSO component, a LAN, an L3-VPN + + Examples: an MSO component, a LAN, an L3-VPN + ONAP terms ----------- +^^^^^^^^^^ - AA&I vs AAI: AAI should be used. - APP-C vs APPC: APPC should be used. - SDN-C vs SDNC: SDNC should be used. @@ -59,19 +60,20 @@ ONAP terms - run time (noun). Example: "logging of events at run time". GUI elements ------------- +^^^^^^^^^^^^ - In general, write menu names as they appear in the UI. For example, if a menu or item name is all caps, then write it all caps in the document. Headings (Titles) ------------------ +^^^^^^^^^^^^^^^^^ - Use brief, but specific, informative titles. Titles should give context when possible. - Use sentence-style capitalization; do not end with a period or colon. - Use a gerund to begin section titles. Examples: Configuring, Managing, Starting. - Use descriptive titles for tables and figures titles. Do not number tables or figures. Do not (in general) add titles for screen shots. Tasks ------ +^^^^^ - Start task titles with an action word. Examples: Create, Add, Validate, Update. - Use [Optional] at the beginning of an optional step. - Provide information on the expected outcome of a step, especially when it is not obvious. - Break down end-to-end tasks into manageable chunks. + |