diff options
| author |   thmsdt <thomas.kulik@telekom.de> | 2022-08-02 13:28:17 +0200 |
|---|---|---|
| committer | thmsdt <thomas.kulik@telekom.de> | 2022-08-04 11:51:51 +0200 |
| commit | 21d59414fca273aade30aa4209aca9bb35a5f78f (patch) | |
| tree | bd1a7449fddb04204f3c759b2877b49f92fe6a17 /docs/guides/onap-developer | |
| parent | 830bc298c26764f3d98f3ca98adf7b3c1b3d0a3a (diff) | |
update and rearrange documentation related content
Issue-ID: DOC-798
Signed-off-by: thmsdt <thomas.kulik@telekom.de>
Change-Id: Id454ec5f09903efb81123669e6eb024f21a08797
Diffstat (limited to 'docs/guides/onap-developer')
29 files changed, 3 insertions, 2604 deletions
diff --git a/docs/guides/onap-developer/how-to-use-docs/CLA_types.png b/docs/guides/onap-developer/contribution/CLA_types.png Binary files differindex d687135af..d687135af 100644 --- a/docs/guides/onap-developer/how-to-use-docs/CLA_types.png +++ b/docs/guides/onap-developer/contribution/CLA_types.png diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/contribution/index.rst index 0ae410bac..ffe4f467e 100644 --- a/docs/guides/onap-developer/how-to-use-docs/index.rst +++ b/docs/guides/onap-developer/contribution/index.rst @@ -1,20 +1,10 @@ .. This work is licensed under a Creative Commons Attribution 4.0 .. International License. http://creativecommons.org/licenses/by/4.0 -Creating Documentation -====================== +Contribution +============ .. toctree:: :maxdepth: 2 - introduction - setting-up setting-up-environment - style-guide - api-swagger-guide - converting-to-rst - -.. toctree:: - :hidden: - - update-review.rst diff --git a/docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst b/docs/guides/onap-developer/contribution/setting-up-environment.rst index 341279b99..341279b99 100644 --- a/docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst +++ b/docs/guides/onap-developer/contribution/setting-up-environment.rst diff --git a/docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst b/docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst deleted file mode 100644 index bb4706c2e..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2019 Orange. All rights reserved. - -.. _api-swagger-guide: - -API documentation -================= - -Swagger -------- - -The API should be described using OpenAPI specifications and available as a -`JSON file <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md>`_ - -A Swagger editor is available here `<http://editor.swagger.io/>`_ to generate -such JSON files. - -As a result, you should get one JSON file per API. For example the project -**my** has 2 API: **myAPI1** and **myAPI2**. - -- myAPI1.json -- myAPI2.json - -Global API table ----------------- -It is recommended to list the following API available with an access to the -Swagger JSON files to help the developers/users to play with JSON. - -We propose the following table: - -.. csv-table:: - :header: "API name", "Swagger JSON" - :widths: 10,5 - - "myAPI1", ":download:`link <myAPI1.json>`" - "myAPI12", ":download:`link <myAPI2.json>`" - -.. note:: - During documentation merge/publish at RTD, any file referenced in an RST file with - ':download:' and relative path to a contributing project repository is copied, uniquely - named, and published with the generated HTML pages. - -The code is available here: - -.. code:: rst - - .. csv-table:: - :header: "API name", "Swagger JSON" - :widths: 10,5 - - "myAPI1", ":download:`link <myAPI1.json>`" - "myAPI2", ":download:`link <myAPI2.json>`" - -.. note:: - The syntax of <myAPI1.json> is to be taken literally. Keep '<' and '>'. - - -API Swagger ------------ -For each API, the ``swaggerv2doc`` directive must be used as follows: - -.. note:: - Note the “v” in swaggerv2doc! - If your JSON file has multiple endpoints, this directive does not preserve the order. - -.. note:: - swaggerv2doc directive may generate errors when Swagger file contains specific - information. In such case, do not use this direcive. - -.. code:: rst - - myAPI1 - ...... - .. swaggerv2doc:: myAPI1.json - - myAPI2 - ...... - .. swaggerv2doc:: myAPI2.json - -It will produce the following output: - -myAPI1 -...... -.. swaggerv2doc:: myAPI1.json - -myAPI2 -...... -.. swaggerv2doc:: myAPI2.json diff --git a/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst b/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst deleted file mode 100644 index edbf1e219..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2017 AT&T Intellectual Property. All rights reserved. - -.. _converting-to-rst: - -Converting to RST -================= - -RST format is used for documentation. Other file formats can be converted to -RST with pandoc. - -.. caution:: - - Always check the output text after conversion. For the most common errors, - see section Fixing the converted document. - -Installing pandoc ------------------ - -Pandoc is a powerful document-transformation utility. We'll use it to -do simple conversions, but it is capable of much more. Visit -the `pandoc website <http://pandoc.org/installing.html>`_ for -installation instructions for your platform. - -Converting ----------- - -Using a terminal, navigate to the directory containing the documents -you wish to convert. Next, issue the following command for each file -you'd like to convert: - -:code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>` - -:code:`-s` tells pandoc to produce a standalone document - -:code:`--toc` tells pandoc to produce a table of contents (optional) - -:code:`-t` tells pandoc to produce reStructuredText output - -:code:`-f` tells pandoc the input format. It should be one of the following: - -+--------------------+----------------------------------------------------+ -| Format | Description | -+====================+====================================================+ -|commonmark | Markdown variant | -+--------------------+----------------------------------------------------+ -|docbook | XML-based markup | -+--------------------+----------------------------------------------------+ -|docx | Microsoft Word | -+--------------------+----------------------------------------------------+ -|epub | Ebook format | -+--------------------+----------------------------------------------------+ -|haddock | Doc format produced by tool used on Haskell code | -+--------------------+----------------------------------------------------+ -|html | HTML | -+--------------------+----------------------------------------------------+ -|json | JSON pandoc AST | -+--------------------+----------------------------------------------------+ -|latex | Older typesetting syntax | -+--------------------+----------------------------------------------------+ -|markdown | Simple formatting syntax meant to produce HTML | -+--------------------+----------------------------------------------------+ -|markdown_github | Github flavored markdown | -+--------------------+----------------------------------------------------+ -|markdown_mmd | Multi-markdown flavored markdown | -+--------------------+----------------------------------------------------+ -|markdown_phpextra | PHP flavored markdown | -+--------------------+----------------------------------------------------+ -|markdown_strict | Markdown with no added pandoc features | -+--------------------+----------------------------------------------------+ -|mediawiki | Popular wiki language | -+--------------------+----------------------------------------------------+ -|native | Pandoc native Haskell | -+--------------------+----------------------------------------------------+ -|odt | Open document text (used by LibreOffice) | -+--------------------+----------------------------------------------------+ -|opml | Outline processor markup language | -+--------------------+----------------------------------------------------+ -|org | Org mode for Emacs | -+--------------------+----------------------------------------------------+ -|rst | reStructuredText | -+--------------------+----------------------------------------------------+ -|t2t | Wiki-like formatting syntax | -+--------------------+----------------------------------------------------+ -|textile | A formatting syntax similar to RST and markdown | -+--------------------+----------------------------------------------------+ -|twiki | Popular wiki formatting syntax | -+--------------------+----------------------------------------------------+ - -Fixing the converted document ------------------------------ - -How much you'll need to fix the converted document depends on which file -format you're converting from. Here are a couple of things to watch out -for: - -1. Multi-line titles need to be converted to single line -2. Standalone "**" characters -3. :code:`***bolded***` should be :code:`**bolded**` -4. Mangled tables - -Previewing edits ----------------- - -Web-based -~~~~~~~~~ - -`Online Sphinx editor <https://livesphinx.herokuapp.com/>`_ is a RST previewing -tool. diff --git a/docs/guides/onap-developer/how-to-use-docs/git_branches.png b/docs/guides/onap-developer/how-to-use-docs/git_branches.png Binary files differdeleted file mode 100644 index 00c698451..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/git_branches.png +++ /dev/null diff --git a/docs/guides/onap-developer/how-to-use-docs/git_branches.svg b/docs/guides/onap-developer/how-to-use-docs/git_branches.svg deleted file mode 100644 index faddef9cf..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/git_branches.svg +++ /dev/null @@ -1,620 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="245.00406mm" - height="55.2243mm" - viewBox="0 0 245.00405 55.2243" - version="1.1" - id="svg8" - inkscape:version="0.92.1 r15371" - sodipodi:docname="git_branches.svg" - inkscape:export-filename="/home/edby8475/Documents/Projets_Orange/ONAP/git_branches.png" - inkscape:export-xdpi="96" - inkscape:export-ydpi="96"> - <defs - id="defs2"> - <marker - inkscape:stockid="Arrow1Lend" - orient="auto" - refY="0" - refX="0" - id="marker8537" - style="overflow:visible" - inkscape:isstock="true"> - <path - id="path8535" - d="M 0,0 5,-5 -12.5,0 5,5 Z" - style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" - transform="matrix(-0.8,0,0,-0.8,-10,0)" - inkscape:connector-curvature="0" /> - </marker> - <marker - inkscape:isstock="true" - style="overflow:visible" - id="marker7039" - refX="0" - refY="0" - orient="auto" - inkscape:stockid="Arrow1Lend" - inkscape:collect="always"> - <path - transform="matrix(-0.8,0,0,-0.8,-10,0)" - style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" - d="M 0,0 5,-5 -12.5,0 5,5 Z" - id="path7037" - inkscape:connector-curvature="0" /> - </marker> - <marker - inkscape:isstock="true" - style="overflow:visible" - id="marker5938" - refX="0" - refY="0" - orient="auto" - inkscape:stockid="Arrow1Lend"> - <path - transform="matrix(-0.8,0,0,-0.8,-10,0)" - style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" - d="M 0,0 5,-5 -12.5,0 5,5 Z" - id="path5936" - inkscape:connector-curvature="0" /> - </marker> - <marker - inkscape:isstock="true" - style="overflow:visible" - id="marker5459" - refX="0" - refY="0" - orient="auto" - inkscape:stockid="Arrow1Lend"> - <path - transform="matrix(-0.8,0,0,-0.8,-10,0)" - style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" - d="M 0,0 5,-5 -12.5,0 5,5 Z" - id="path5457" - inkscape:connector-curvature="0" /> - </marker> - <marker - inkscape:stockid="Arrow1Lend" - orient="auto" - refY="0" - refX="0" - id="Arrow1Lend" - style="overflow:visible" - inkscape:isstock="true" - inkscape:collect="always"> - <path - id="path4715" - d="M 0,0 5,-5 -12.5,0 5,5 Z" - style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" - transform="matrix(-0.8,0,0,-0.8,-10,0)" - inkscape:connector-curvature="0" /> - </marker> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="0.7" - inkscape:cx="309.86346" - inkscape:cy="-20.987063" - inkscape:document-units="mm" - inkscape:current-layer="layer1" - showgrid="true" - inkscape:window-width="1680" - inkscape:window-height="986" - inkscape:window-x="0" - inkscape:window-y="27" - inkscape:window-maximized="1" - fit-margin-top="0" - fit-margin-left="0" - fit-margin-right="0" - fit-margin-bottom="0"> - <inkscape:grid - type="xygrid" - id="grid10" - units="cm" - spacingx="2" - spacingy="2" - originx="91.41838" - originy="-115.8675" /> - </sodipodi:namedview> - <metadata - id="metadata5"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Calque 1" - inkscape:groupmode="layer" - id="layer1" - transform="translate(91.418392,-125.9082)"> - <path - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 149.99999,157 h -240" - id="path3682" - inkscape:connector-curvature="0" - sodipodi:nodetypes="cc" /> - <path - inkscape:connector-curvature="0" - id="path3693" - d="m -50.000022,157 -10,-10 h 1.2e-5 l -10,10" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - sodipodi:nodetypes="cccc" /> - <path - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 20.000002,157 -10,-10 h -50 l -10,10" - id="path3695" - inkscape:connector-curvature="0" - sodipodi:nodetypes="cccc" /> - <path - inkscape:connector-curvature="0" - id="path3697" - d="m 10.000002,147.05417 -10.02863,-10 h -19.911584 l -10.059786,10" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - sodipodi:nodetypes="cccc" /> - <path - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 149.99999,167 h -90 l -10,-10" - id="path3699" - inkscape:connector-curvature="0" - sodipodi:nodetypes="ccc" /> - <path - inkscape:connector-curvature="0" - id="path3701" - d="m 50.000002,157 -10,-10 h -10 l -10,10" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - sodipodi:nodetypes="cccc" /> - <circle - id="path3709" - cx="-156.91447" - cy="-70.053894" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="-172.98799" - y="48.645218" - id="text3713" - transform="rotate(-45)"><tspan - sodipodi:role="line" - id="tspan3711" - x="-172.98799" - y="48.645218" - style="font-size:2.82222223px;stroke-width:0.26458332">Master</tspan></text> - <circle - r="2.5" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - cy="-60.43219" - cx="-147.15913" - id="circle3715" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - cy="-49.718792" - cx="-157.04811" - id="circle3719" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - cy="-39.963455" - cx="-147.15913" - id="circle3721" - transform="rotate(-90)" /> - <circle - id="circle3723" - cx="-147.15913" - cy="-30.341751" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - cy="-20.051872" - cx="-137.03445" - id="circle3725" - transform="rotate(-90)" /> - <circle - id="circle3727" - cx="-147.15913" - cy="-10.029264" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - cy="0.39425087" - cx="-137.03445" - id="circle3729" - transform="rotate(-90)" /> - <circle - id="circle3731" - cx="-147.15913" - cy="10.015955" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - cy="20.172205" - cx="-157.0481" - id="circle3733" - transform="rotate(-90)" /> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="-151.95352" - y="57.447376" - id="text3713-3" - transform="rotate(-45)"><tspan - sodipodi:role="line" - id="tspan3711-6" - x="-151.95352" - y="57.447376" - style="font-size:2.82222223px;stroke-width:0.26458332">Feature1</tspan></text> - <text - transform="rotate(-45)" - id="text3765" - y="71.835785" - x="-137.57268" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - style="font-size:2.82222223px;stroke-width:0.26458332" - y="71.835785" - x="-137.57268" - id="tspan3763" - sodipodi:role="line">Feature2</tspan></text> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="-127.77207" - y="78.916374" - id="text3769" - transform="rotate(-45)"><tspan - sodipodi:role="line" - x="-127.77207" - y="78.916374" - style="font-size:2.82222223px;stroke-width:0.26458332" - id="tspan3775">enhanced feature2</tspan></text> - <circle - id="circle3779" - cx="-167.0166" - cy="59.71204" - style="fill:#008000;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - id="circle3781" - cx="-147.15913" - cy="30.178896" - style="fill:#ff0000;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#ff0000;stroke:#000000;stroke-width:0.33072913" - cy="40.195267" - cx="-147.15913" - id="circle3783" - transform="rotate(-90)" /> - <text - transform="rotate(-45)" - id="text3787" - y="121.33652" - x="-87.108055" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - id="tspan3785" - style="font-size:2.82222223px;stroke-width:0.26458332" - y="121.33652" - x="-87.108055" - sodipodi:role="line">bugfix1</tspan></text> - <path - sodipodi:nodetypes="cccc" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 79.99999,157 -10,-10 h 1.2e-5 l -20,10" - id="path3800" - inkscape:connector-curvature="0" /> - <circle - r="2.5" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - cy="69.971039" - cx="-147.15913" - id="circle3802" - transform="rotate(-90)" /> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="-59.193871" - y="149.89697" - id="text3808" - transform="rotate(-45)"><tspan - sodipodi:role="line" - x="-59.193871" - y="149.89697" - style="font-size:2.82222223px;stroke-width:0.26458332" - id="tspan3806">feature3</tspan></text> - <path - inkscape:connector-curvature="0" - id="path3833" - d="m 99.99999,157 -10,-10 h 1.2e-5 l -10,10" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - sodipodi:nodetypes="cccc" /> - <path - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 99.99999,167 -10,-20" - id="path3856" - inkscape:connector-curvature="0" - sodipodi:nodetypes="cc" /> - <circle - id="circle3835" - cx="-147.15913" - cy="90.082069" - style="fill:#ff0000;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <text - transform="rotate(-45)" - id="text3841" - y="164.13176" - x="-45.183849" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - id="tspan3839" - style="font-size:2.82222223px;stroke-width:0.26458332" - y="164.13176" - x="-45.183849" - sodipodi:role="line">bugfix2</tspan></text> - <circle - id="circle3798" - cx="-157.0481" - cy="49.839127" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - id="circle3819" - cx="-157.31537" - cy="79.662285" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#008000;stroke:#000000;stroke-width:0.33072913" - cy="100.02003" - cx="-167.09488" - id="circle3854" - transform="rotate(-90)" /> - <path - inkscape:connector-curvature="0" - id="path3858" - d="m 130.05422,157 -10,-10 h -10 l -10.05423,10" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - sodipodi:nodetypes="cccc" /> - <circle - id="circle3860" - cx="-147.15913" - cy="110.10485" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#d45500;stroke:#000000;stroke-width:0.33072913" - cy="120.12096" - cx="-147.15913" - id="circle3862" - transform="rotate(-90)" /> - <text - transform="rotate(-45)" - id="text3866" - y="178.45798" - x="-31.003382" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - id="tspan3864" - style="font-size:2.82222223px;stroke-width:0.26458332" - y="178.45798" - x="-31.003382" - sodipodi:role="line">feature4</tspan></text> - <circle - id="circle3868" - cx="-156.91447" - cy="130.27434" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - r="2.5" - transform="rotate(-90)" /> - <path - sodipodi:nodetypes="ccc" - inkscape:connector-curvature="0" - id="path3870" - d="m 150.05422,177 h -10 l -10,-20" - style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> - <circle - r="2.5" - style="fill:#008000;stroke:#000000;stroke-width:0.33072913" - cy="139.66118" - cx="-176.98384" - id="circle3872" - transform="rotate(-90)" /> - <circle - r="2.5" - style="fill:#0000ff;stroke:#000000;stroke-width:0.33072913" - cy="100.02017" - cx="-156.91447" - id="circle3843" - transform="rotate(-90)" /> - <text - id="text3876" - y="165.63252" - x="63.213688" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - id="tspan3874" - style="font-size:2.82222223px;stroke-width:0.26458332" - y="165.63252" - x="63.213688" - sodipodi:role="line">stable/A</tspan></text> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="142.27473" - y="174.96959" - id="text3880"><tspan - sodipodi:role="line" - x="142.27473" - y="174.96959" - style="font-size:2.82222223px;stroke-width:0.26458332" - id="tspan3878">stable/B</tspan></text> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="6.8720784" - y="167.3783" - id="text3903"><tspan - sodipodi:role="line" - id="tspan3901" - x="6.8720784" - y="167.3783" - style="font-size:3.52777767px;stroke-width:0.26458332">Stable branch creation</tspan></text> - <path - style="fill:none;stroke:#000000;stroke-width:0.26499999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Lend)" - d="M 6.4666547,169 H 48.46666 l 6.000001,-6" - id="path3905" - inkscape:connector-curvature="0" /> - <text - id="text5453" - y="172.20334" - x="56.934578" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - style="font-size:3.52777767px;stroke-width:0.26458332" - y="172.20334" - x="56.934578" - id="tspan5451" - sodipodi:role="line">cherry pick bugfix2</tspan></text> - <path - inkscape:connector-curvature="0" - id="path5455" - d="m 57.649986,173.82498 h 34 l 4.350004,-14" - style="fill:none;stroke:#000000;stroke-width:0.26499999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker5459)" - sodipodi:nodetypes="ccc" /> - <text - id="text5932" - y="179.3783" - x="88.459633" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - style="font-size:3.52777767px;stroke-width:0.26458332" - y="179.3783" - x="88.459633" - id="tspan5930" - sodipodi:role="line">Stable branch creation</tspan></text> - <path - inkscape:connector-curvature="0" - id="path5934" - d="m 88.05421,181 h 42 l 6,-10" - style="fill:none;stroke:#000000;stroke-width:0.26499999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker5938)" - sodipodi:nodetypes="ccc" /> - <circle - transform="rotate(-90)" - r="2.5" - style="fill:none;stroke:#000000;stroke-width:0.33072913" - cy="-87.251816" - cx="-129.88918" - id="circle6900" /> - <text - id="text6914" - y="131.28157" - x="-84.371376" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - style="font-size:3.52777767px;stroke-width:0.26458332" - y="131.28157" - x="-84.371376" - id="tspan6912" - sodipodi:role="line">=1 commit</tspan></text> - <text - id="text7033" - y="172.37086" - x="-49.921974" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - style="font-size:3.52777767px;stroke-width:0.26458332" - y="172.37086" - x="-49.921974" - sodipodi:role="line" - id="tspan7461">merge branch 'feature1'</tspan></text> - <path - inkscape:connector-curvature="0" - id="path7035" - d="m -30.00001,177 h -20 l -6,-26" - style="fill:none;stroke:#000000;stroke-width:0.26499999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker7039)" - sodipodi:nodetypes="ccc" /> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="-49.921974" - y="176.07498" - id="text7473"><tspan - id="tspan7471" - sodipodi:role="line" - x="-49.921974" - y="176.07498" - style="font-size:3.52777767px;stroke-width:0.26458332">to master branch</tspan></text> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - x="-91.499352" - y="167.07919" - id="text8521"><tspan - id="tspan8519" - sodipodi:role="line" - x="-91.499352" - y="167.07919" - style="font-size:3.52777767px;stroke-width:0.26458332">create branch</tspan></text> - <text - id="text8525" - y="170.78331" - x="-91.499352" - style="font-style:normal;font-weight:normal;font-size:10.58333302px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332" - xml:space="preserve"><tspan - style="font-size:3.52777767px;stroke-width:0.26458332" - y="170.78331" - x="-91.499352" - sodipodi:role="line" - id="tspan8523">for 'feature1'</tspan></text> - <path - sodipodi:nodetypes="ccc" - style="fill:none;stroke:#000000;stroke-width:0.30303907;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker8537)" - d="m -90.00001,173 h 24 l 2,-22" - id="path8533" - inkscape:connector-curvature="0" /> - </g> -</svg> diff --git a/docs/guides/onap-developer/how-to-use-docs/introduction.rst b/docs/guides/onap-developer/how-to-use-docs/introduction.rst deleted file mode 100644 index 242a2d239..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/introduction.rst +++ /dev/null @@ -1,226 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2017 AT&T Intellectual Property. All rights reserved. - -Introduction -============ -This guide describes how to create documentation for the Open Network -Automation Platform (ONAP). ONAP projects create a variety of -content depending on the nature of the project. For example projects -delivering a platform component may have different types of content than -a project that creates libraries for a software development kit. -The content from each project may be used together as a reference for -that project and/or be used in documents that are tailored to a specific -user audience and tasks 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. - -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 in later sections of this Developer Documentation Guide. - -.. _ReStructuredText: http://docutils.sourceforge.net/rst.html - -Why reStructuredText/Sphinx? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the past, standard documentation methods included ad-hoc Word documents, -PDFs, poorly organized Wikis, and other, often closed, tools like -Adobe FrameMaker. The rise of DevOps, Agile, and Continuous Integration, -however, created a paradigm shift for those who care about documentation -because: - -1. Documentation must be tightly coupled with code/product releases. - In many cases, particularly with open-source products, many different - versions of the same code can be installed in various production - environments. DevOps personnel must have access to the correct version - of documentation. - -2. Resources are often tight, volunteers scarce. With a large software base - like ONAP, a small team of technical writers, even if they are also - developers, cannot keep up with a constantly changing, large code base. - Therefore, those closest to the code should document it as best they can, - and let professional writers edit for style, grammar, and consistency. - -Plain-text formatting syntaxes, such as reStructuredText, Markdown, -and Textile, are a good choice for documentation because: - -a. They are editor agnostic - -b. The source is nearly as easy to read as the rendered text - -c. Documentation can be treated exactly as source code is (e.g. versioned, - diff'ed, associated with commit messages that can be included - in rendered docs) - -d. Shallow learning curve - -The documentation team chose reStructuredText largely because of Sphinx, -a Python-based documentation build system, which uses reStructuredText -natively. In a code base as large as ONAP's, cross-referencing between -component documentation was deemed critical. Sphinx and reStructuredText -have built-in functionality that makes collating and cross-referencing -component documentation easier. - -Which docs should go where? -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Frequently, developers ask where documentation should be created. Should -they always use reStructuredText/Sphinx? Not necessarily. Is the wiki -appropriate for anything at all? Yes. - -It's really up to the development team. Here is a simple rule: - -The more tightly coupled the documentation is to a particular version -of the code, the more likely it is that it should be stored with the -code in reStructuredText. - -The doc team encourages component teams to store as much documentation -as reStructuredText as possible because: - -1. It is easier to edit component documentation for grammar, - spelling, clarity, and consistency. - -2. A consistent formatting syntax across components will allow - flexibility in producing different kinds of output. - -3. It is easier to re-organize the documentation. - -4. Wiki articles tend to grow in size and not maintained making it hard - to find current information. - -Structure ---------- -A top level master document structure is used to organize all -documents created by ONAP projects and this resides in the gerrit doc -repository. Complete documents or guides may reside here and -reference parts of source for documentation from other project -repositories. Other ONAP projects will provide content that -is referenced from this structure. - -.. code-block:: - - docs - ├── guides - │ ├── onap-developer - │ │ ├── apiref - │ │ ├── architecture - │ │ │ └── media - │ │ ├── developing - │ │ └── how-to-use-docs - | | | ├── templates - │ | | | ├── collections - │ | | | └── sections - │ ├── onap-operator - │ │ ├── cloud_site - │ │ │ ├── aws - │ │ │ ├── azure - │ │ │ ├── k8s - │ │ │ ├── openstack - │ │ │ └── vmware - │ │ ├── onap-portal-admin - │ │ │ └── attachments - │ │ └── settingup - │ ├── onap-provider - │ ├── onap-user - │ │ ├── configure - │ │ │ ├── change_config - │ │ │ ├── pnf_connect - │ │ │ └── vnf_connect - │ │ ├── design - │ │ │ ├── control-loop - │ │ │ │ └── media - │ │ │ ├── media - │ │ │ ├── parameter_resolution - │ │ │ │ └── ubuntu_example - │ │ │ │ ├── cba-after-enrichment - │ │ │ │ │ ├── Definitions - │ │ │ │ │ ├── Templates - │ │ │ │ │ └── TOSCA-Metadata - │ │ │ │ ├── cba-before-enrichment - │ │ │ │ │ ├── Definitions - │ │ │ │ │ ├── Templates - │ │ │ │ │ └── TOSCA-Metadata - │ │ │ │ └── ubuntuCDS_heat - │ │ │ ├── pre-onboarding - │ │ │ │ └── media - │ │ │ ├── resource-onboarding - │ │ │ │ └── media - │ │ │ ├── service-design - │ │ │ │ └── media - │ │ │ ├── service-distribution - │ │ │ │ └── media - │ │ │ └── vfcreation - │ │ │ └── media - │ │ ├── instantiate - │ │ │ ├── instantiation - │ │ │ │ ├── nbi - │ │ │ │ ├── pnf_instance - │ │ │ │ ├── service_instance - │ │ │ │ ├── so1 - │ │ │ │ ├── so2 - │ │ │ │ ├── uui - │ │ │ │ ├── vid - │ │ │ │ ├── virtual_link_instance - │ │ │ │ └── vnf_instance - │ │ │ └── pre_instantiation - │ │ └── onap-portal-user - │ │ └── attachments - │ └── overview - │ └── media - └── release - - -Source Files ------------- -All documentation for project repositories 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 -RST file changes in the top level docs directory and below. - -Licensing ---------- -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. - .. http://creativecommons.org/licenses/by/4.0 - .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL - - These lines will not be rendered in the html and pdf files. - -When there are subsequent, significant contributions to a source file -from a different contributor, a new copyright line may be appended -after the last existing copyright line. - -Read The Docs URLs ------------------- - -When referencing versions of documentation a Read The Docs the following -URL conventions should be used - - +----------------------------------+----------------------------------------+ - | URL | To Refer to | - +==================================+========================================+ - | docs.onap.org | Most recent approved named release | - +----------------------------------+----------------------------------------+ - | docs.onap.org/en/latest | Latest master branch all projects | - +----------------------------------+----------------------------------------+ - | docs.onap.org/en/*named release* | An approved name release eg. amsterdam | - +----------------------------------+----------------------------------------+ diff --git a/docs/guides/onap-developer/how-to-use-docs/myAPI1.json b/docs/guides/onap-developer/how-to-use-docs/myAPI1.json deleted file mode 100644 index b611ad81c..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/myAPI1.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "swagger" : "2.0", - "info" : { - "description" : "my API 1", - "version" : "1.0.0", - "title" : "API example", - "contact" : { - "email" : "onap@orange.com" - }, - "license" : { - "name" : "Apache 2.0", - "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" - } - }, - "host" : "serverRoot", - "basePath" : "/healthCheck", - "schemes" : [ "https" ], - "produces": [ - "application/json;charset=utf-8" - ], - "paths" : { - "/healthCheck" : { - "get" : { - "summary" : "Displays healhcheck for my favorite component", - "description" : "Displays healthcheck for my favorite component", - "responses": { - "200": { - "description": "Service OK" - }, - "503" : { - "description" : "Service Unavailable" - } - } - } - } - } -} diff --git a/docs/guides/onap-developer/how-to-use-docs/myAPI2.json b/docs/guides/onap-developer/how-to-use-docs/myAPI2.json deleted file mode 100644 index 473d351b2..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/myAPI2.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "swagger" : "2.0", - "info" : { - "description" : "my API 2", - "version" : "1.0.0", - "title" : "API example", - "contact" : { - "email" : "onap@orange.com" - }, - "license" : { - "name" : "Apache 2.0", - "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" - } - }, - "host" : "serverRoot", - "basePath" : "/status", - "schemes" : [ "https" ], - "produces": [ - "application/json;charset=utf-8" - ], - "paths" : { - "/status" : { - "get" : { - "summary" : "Displays status for my favorite component", - "description" : "Displays status for my favorite component", - "responses": { - "200": { - "description": "Service OK" - }, - "503" : { - "description" : "Service Unavailable" - } - } - } - } - } -} diff --git a/docs/guides/onap-developer/how-to-use-docs/setting-up.rst b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst deleted file mode 100644 index 789cf0b9d..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/setting-up.rst +++ /dev/null @@ -1,681 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2017 AT&T Intellectual Property. All rights reserved. - - -Setting Up -========== - -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. - -Authors create source for documents in reStructured Text (RST) that is -rendered to HTML 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. - -Some initial set up is required to connect a project with -the master document structure and enable automated publishing of -changes as summarized in the following diagram and description below -below. - -.. seqdiag:: - :height: 700 - :width: 1000 - - seqdiag { - 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]; - - PA -> DR [label = "Add project repo as\ngit submodule" ]; - DR -> DA [label = "Review & Plan to\nIntegrate Content with\nTocTree Structure" ]; - DR <-- DA [label = "Vote +2/Merge" ]; - PA <-- DR [label = "Merge Notification" ]; - PA -> PR [label = "Create in project repo\ntop level directory and index.rst" ]; - PR -> DA [label = "Add as Reviewer" ]; - PR <-- DA [label = "Approve and Integrate" ]; - PA <-- PR [label = "Merge" ]; - } - -Setup project repositories --------------------------- -These steps are performed for each project repository that -provides documentation. - -1. Set two variables that will be used in the subsequent steps. -Set *reponame* to the project repository you are setting up -just as it appears in the **Project Name** column of -the Gerrit projects page. -Set *lfid* to your Linux Foundation identity that you use to -login to gerrit or for git clone requests over ssh. - -.. code-block:: bash - - reponame= - lfid= - -2. Add a directory in the doc project where your -project will be included as a submodule and at least one reference -from the doc project to the documentation index in your repository. -The following sequence will do this over ssh. Please note that the -reference to your project in *repolist.rst* should be considered -temporary and removed when you reference it from more appropriate -place. - -.. caution:: - - If your access network restricts ssh, you will need to use equivalent - git commands and HTTP Passwords as described `here <http://wiki.onap.org/x/X4AP>`_. - -.. caution:: - - Don't replace ../ in *git submodule add* with any relative path on - your local file system. It refers to the location of your repository - on the server. - -.. code-block:: bash - - git clone ssh://$lfid@gerrit.onap.org:29418/doc - cd doc - mkdir -p `dirname docs/submodules/$reponame` - git submodule add ../$reponame docs/submodules/$reponame.git - git submodule init docs/submodules/$reponame.git - git submodule update docs/submodules/$reponame.git - - echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst - - git add . - git commit -s - git review - -.. caution:: - Wait for the above change to be merged before any merge to the - project repository that you have just added as a submodule. - If the project repository added as submodule changes before the - doc project merge, git may not automatically update the submodule - reference on changes and/or the verify job will fail in the step below. - - -3. Create a docs directory in your repository with -an index.rst file. The following sequence will complete the minimum -required over ssh. As you have time to convert or add new content you -can update the index and add files under the docs folder. - -.. hint:: - If you have additional content, you can include it by editing the - index.rst file and/or adding other files before the git commit. - See `Templates and Examples`_ below and :ref:`converting-to-rst` - for more information. - - -.. code-block:: bash - - git clone ssh://$lfid@gerrit.onap.org:29418/$reponame - cd $reponame - mkdir docs - echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. - - TODO Add files to toctree and delete this header - ------------------------------------------------ - .. toctree:: - :maxdepth: 1 - - " > docs/index.rst - - git add . - git commit -s - git review - - -The diagram below illustrates what is accomplished in the setup steps -above from the perspective of a file structure created for a local test, -a jenkins verify job, and/or published release documentation including: - -- ONAP gerrit project repositories, - -- doc project repository master document index.rst, templates, - configuration, and other documents - -- submodules directory where other project repositories and - directories/files are referenced - -- file structure: directories (ellipses), files(boxes) - -- references: directory/files (solid edges), git submodule - (dotted edges), sphinx toctree (dashed edges) - -.. graphviz:: - - - digraph docstructure { - size="8,12"; - node [fontname = "helvetica"]; - // Align gerrit repos and docs directories - {rank=same doc aaf aai reponame repoelipse vnfsdk vvp} - {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} - {rank=same releasedocumentindex releaserepolist} - - //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/" ]; - doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"]; - gerrit -> doc; - gerrit -> aaf; - gerrit -> aai; - gerrit -> reponame; - gerrit -> repoelipse; - repoelipse [label=". . . ."]; - gerrit -> vnfsdk; - gerrit -> vvp; - - //Show example of local reponame instance of component info - reponame -> reponamedocsdir; - reponamesm -> reponamedocsdir; - reponamedocsdir [label="docs"]; - reponamedocsdir -> repnamedocsdirindex; - repnamedocsdirindex [label="index.rst", shape=box]; - - //Show detail structure of a portion of doc/docs - doc -> docs; - docs -> confpy; - confpy [label="conf.py",shape=box]; - docs -> masterindex; - masterindex [label="Master\nindex.rst", shape=box]; - docs -> release; - docs -> templates; - docs -> otherdocdocumentelipse; - otherdocdocumentelipse [label="...other\ndocuments"]; - docs -> submodules - - masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"]; - - //Show submodule linkage to docs directory - submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"]; - reponamesm [label="reponame.git"]; - - //Example Release document index that references component info provided in other project repo - release -> releasedocumentindex; - releasedocumentindex [label="index.rst", shape=box]; - releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; - releaserepolist [label="repolist.rst", shape=box]; - release -> releaserepolist; - releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"]; - - } - -Branches in the DOC Project ---------------------------- - -The DOC project 'master' branch aggregates the 'latest' content -from all ONAP project repositories contributing documentation into a -single tree file structure as described in the previous section. This -branch is continuously integrated and deployed at Read The -Docs as the 'latest' ONAP Documentation by: - -* Jenkins doc-verify-rtd and doc-merge-rtd jobs triggered whenever patches on - contributing repositories contain rst files at or below a top level - 'docs' folder. - -* Subscription in the DOC project to changes in submodule repositories. - These changes appear in the DOC project as commits with title - 'Updated git submodules' when a change to a contributing project - repository is merged. No DOC project code review occurs, only a - submodule repository commit hash is updated to track the head of each - contributing master branch. - -For each ONAP named release the DOC project creates a branch with the -release name. The timing of the release branch is determined by -work needed in the DOC project to prepare the release branch and the -amount of change unrelated to the release in the master branch. -For example contributing projects that create named release branches -early to begin work on the next release and/or contributing projects -to the master that are not yet part of the named release would result -in an earlier named release branch to cleanly separate work to stabilize -a release from other changes in the master branch. - -A named release branch is integrated and deployed at Read The Docs -as the 'named release' by aggregating content from contributing -project repositories. A contributing project repository can -choose one of the following for the 'named release' branch: - -* Remove the contributing project repository submodule and RST - references when not part of the named release. - -* Provide a commit hash or tag for the contributing project master - branch to be used for the life of the release branch or until a - request is submitted to change the commit hash or tag. - -* Provide the commit hash for the head of a named release branch - created in the contributing project repository. This option - may be appropriate if frequent changes are expected over the - life of the named release and work the same way as the continuous - integration and deployment described for the master branch. - -The decision on option for each contributing project repository -can be made or changed before the final release is approved. The -amount of change and expected differences between master and a -named release branch for each repository should drive the choice of -option and timing. - -About GIT branches ------------------- - -GIT is a powerful tool allowing many actions, but without respecting some rules -the GIT structure can be quickly hard to maintain. - -Here are some conventions about GIT branches: - - - ALWAYS create a local branch to edit or create any file. This local branch - will be considered as a topic in Gerrit and allow contributors to - work at the same time on the same project. - - - 1 feature = 1 branch. In the case of documentation, a new chapter - or page about a new code feature can be considered as a 'doc feature' - - - 1 bug = 1 branch. In the case of documentation, a correction on an - existing sentence can be considered as a 'doc bug' - - - the master branch is considered as "unstable", containing new features that - will converge to a stable situation for the release date. - -The day of the release, the repository owner will create a new branch to -fix the code and documentation. This will represent the 'stable' code of the -release. In this context: - - - NEVER push a new feature on a stable branch - - - Only bug correction are authorized on a stable branch using - cherry pick method - -.. image:: git_branches.png - -Creating Restructured Text -========================== - -ReStructuredText markup conventions ------------------------------------ -For detailed information on 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>`_ - - -Templates and Examples ----------------------- -Templates are available that capture the kinds of information -useful for different types of projects and provide some examples of -restructured text. We organize templates in the following way to: - - - help authors understand relationships between documents - - - keep the user audience context in mind when writing and - - - tailor sections for different kinds of projects. - - -**Sections** Represent a certain type of content. A section -is **provided** in an project repository, to describe something about -the characteristics, use, capability, etc. of things in that repository. -A section may also be **referenced** from other sections and in -other repositories. For example, an API specification provided in a project -repository might be referenced to in a Platform API Reference Guide. -The notes in the beginning of each section template provide -additional detail about what is typically covered and where -there may be references to the section. - -**Collections** Are a set of sections that are typically provided -for a particular type of project, repository, guide, reference manual, etc. -For example, a collection for a platform component, an SDK, etc. - -You can: browse the template *collections* and *sections* below; -show source to look at the Restructured Text and Sphinx directives used. - -Sections -++++++++ - -Section examples are available here: :ref:`Templates<templates>` - -Collections -+++++++++++ - -In addition to these simple templates and examples -there are many open source projects (e.g. Open Daylight, Open Stack) -that are using Sphinx and Readthedocs where you may find examples -to start with. Working with project teams we will continue to enhance -templates here and capture frequently asked questions on the developer -wiki question topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_. - -Each project should: - - - decide what is relevant content - - - determine the best way to create/maintain it in the CI/CD process and - - - work with the documentation team to reference content from the - master index and guides. - -Consider options including filling in a template, identifying existing -content that can be used as is or easily converted, and use of Sphinx -directives/extensions to automatically generate restructured text -from other source you already have. - -Collection examples are available here: :ref:`Templates<templates>` - -Links and References --------------------- -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>`_. - -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``. - -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 built 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. - - -Creating Indices ----------------- - -Building an index for your Sphinx project is relatively simple. First, tell Sphinx that -you want it to build an index by adding something like this after your TOC tree: - -.. code-block:: rst - - Indices and Search - ================== - - * :ref:`genindex` - * :ref:`search` - -**Hint:** -Note that search was included here. It works out of the box with any Sphinx project, so you -don't need to do anything except include a reference to it in your :code:`index.rst` file. - -Now, to generate a index entry in your RST, do one of the following: - -.. code-block:: rst - - Some content that requires an :index:`index`. - -or - -.. code-block:: rst - - .. index:: - single: myterm - - Some header containing myterm - ============================= - -In the second case, Sphinx will create a link in the index to the paragraph that follows -the index entry declaration. - -When your project is built, Sphinx will generate an index page populated with the entries -you created in the source RST. - -These are simple cases with simple options. For more information about indexing with Sphinx, -please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html>`_. - - -Jenkins Jobs ------------- - -Verify Job -++++++++++ - -The verify job name is **doc-{stream}-verify-rtd** - -Proposed changes in files in any repository with top level docs folder -in the repository and RST files in below this folder -will be verified by this job as part of a gerrit code review. - -.. Important:: - The contributing author and every reviewer on a gerrit code review - should always review the Jenkins log before approving and merging a - change. The log review should include: - - * Using a browser or other editor to search for a pattern in the - *console log* that matches files in the patch set. This will quickly - identify errors and warnings that are related to the patch set and - repository being changed. - - * Using a browser to click on the *html* folder included in the log - and preview how the proposed changes will look when published at - Read The Docs. Small changes can be easily made in the patch set. - -Merge Job -+++++++++ - -The merge job name is **doc-{stream}-merge-rtd**. - -When a committer merges a patch that includes files matching the -path described above, the doc project merge job will trigger an -update at readthedocs. There may be some delay after the merge job -completes until new version appears at Read The Docs. - -Testing -======= - -One RST File ------------- -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> - - - -One Project ------------ -To test how the documentation renders in HTML, follow these steps: - -Install `virtual environment <https://pypi.org/project/virtualenv>`_ & create one. - -.. code-block:: bash - - sudo pip install virtualenv - virtualenv onap_docs - -Activate `onap_docs` virtual environment. - -.. code-block:: bash - - source onap_docs/bin/activate - -.. note:: Virtual environment activation has to be performed before attempting to build documentation. - Otherwise, tools necessary for the process might not be available. - -Download a project repository. - -.. code-block:: bash - - git clone http://gerrit.onap.org/r/<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 - pip install -r etc/requirements.txt - -.. warning:: - - Just follow the next step (copying conf.py from Doc project to your project) - if that is your intention, otherwise skip it. Currently all projects should already have a conf.py file. - Through the next step, this file and potential extensions in your project get overriden. - -Copy the conf.py file to your project folder where RST files have been kept: - -.. code-block:: bash - - cp docs/conf.py <path-to-project-folder>/<folder where are rst files> - -Copy the static files to the project folder where RST files have been kept: - -.. code-block:: bash - - cp -r docs/_static/ <path-to-project-folder>/<folder where are rst files> - -Build the documentation from within your project folder: - -.. code-block:: bash - - sphinx-build -b html <path-to-project-folder>/<folder where are rst files> <path-to-output-folder> - -Your documentation shall be built as HTML inside the -specified output folder directory. - -You can use your Web Browser to open -and check resulting html pages in the output folder. - -.. 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. - -.. _building-all-documentation: - -All Documentation ------------------ -To build the all documentation under doc/, follow these steps: - -Install `tox <https://pypi.org/project/tox>`_. - -.. code-block:: bash - - sudo pip install tox - -Download the DOC repository. - -.. code-block:: bash - - git clone http://gerrit.onap.org/r/doc - -Build documentation using tox local environment & then open using any browser. - -.. code-block:: bash - - cd doc - tox -elocal - firefox docs/_build/html/index.html - -.. note:: Make sure to run `tox -elocal` and not just `tox`. - This updates all submodule repositories that are integrated - by the doc project. - -There are additional tox environment options for checking External -URLs and Spelling. Use the tox environment options below and then -look at the output with the Linux `more` or similar command -scan for output that applies to the files you are validating. - -.. code-block:: bash - - tox -elinkcheck - more < docs/_build/linkcheck/output.txt - - tox -espellcheck - more < docs/_build/spellcheck/output.txt diff --git a/docs/guides/onap-developer/how-to-use-docs/style-guide.rst b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst deleted file mode 100644 index 17dee9fda..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/style-guide.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2017 AT&T Intellectual Property. All rights reserved. - -Style guide -=========== - -This style guide is for ONAP documentation contributors, reviewers and -committers. - -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 does not 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 -- Write objective, professional content -- Keep sentences and paragraphs short and clear -- 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 - - -ONAP terminology -^^^^^^^^^^^^^^^^ -- AA&I vs AAI: AAI should be used. - -- APP-C vs APPC: APPC should be used. - -- SDN-C vs SDNC: SDNC should be used. - -- Heat vs HEAT: Both are in use. The official website uses "Heat". - -- life cycle vs lifecycle or life-cycle: "life cycle" is preferred. - -- open source (adjective): capitalize only in titles; avoid - "open-source". (Based on prevalence on the web.) - -- run-time vs. execution-time (adjective): prefer run-time. - Example: "run-time logging of events" - -- 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. - - -ONAP Conventions for the Use of Sphinx Directives -------------------------------------------------- - -Needs Directive -^^^^^^^^^^^^^^^ - - * Needs IDs must match the regular expression "^[A-Z0-9]+-[A-Z0-9]+" - - * The prefix (string before the dash) must be described in the following table - -.. list-table:: Needs Prefix Use - :align: center - :widths: 8 40 40 - :header-rows: 1 - - * - Prefix - - Description - - Use - - * - R - - Represents a requirement that must be met by a VNF provider - - Defined only in the vnfrqts project repositories, may be referenced in any project repository source diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst b/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst deleted file mode 100644 index e776c7ff6..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Platform Component -================== - -.. Add or remove sections below as appropriate for the platform component. - -.. toctree:: - :maxdepth: 1 - - ../sections/architecture.rst - ../sections/offeredapis.rst - ../sections/consumedapis.rst - ../sections/delivery.rst - ../sections/design.rst - ../sections/logging.rst - ../sections/installation.rst - ../sections/configuration.rst - ../sections/administration.rst - ../sections/userinterfaces.rst - ../sections/release-notes.rst diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/collections/sdk.rst b/docs/guides/onap-developer/how-to-use-docs/templates/collections/sdk.rst deleted file mode 100644 index 83fbbe2ee..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/collections/sdk.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -SDK -=== - -.. Add or remove sections below as appropriate for the SDK - -.. toctree:: - :maxdepth: 1 - - ../sections/architecture.rst - ../sections/offeredapis.rst - ../sections/delivery.rst - ../sections/logging.rst - ../sections/build.rst - ../sections/release-notes.rst diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/index.rst b/docs/guides/onap-developer/how-to-use-docs/templates/index.rst deleted file mode 100644 index cda3128ba..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -.. _templates: - -Templates -========= - -This section provides templates for the projects - -.. toctree:: - :maxdepth: 2 - - collections/sdk.rst - collections/platform-component.rst - sections/offeredapis.rst - sections/consumedapis.rst - sections/architecture.rst - sections/design.rst - sections/logging.rst - sections/administration.rst - sections/installation.rst - sections/delivery.rst - sections/userinterfaces.rst - sections/release-notes.rst - sections/build.rst - sections/configuration.rst diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst deleted file mode 100644 index 841a55291..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Administration -============== - -.. - * This section is used to describe a software component from the perspective of on-going - operation including regular processes and actions that are taken to configure and manage - the component. - * This section is typically: provided for platform-component or applications; and - referenced in user guides. - * This note must be removed after content has been added. - - -Procedure ---------- - -.. - Use this section for each procedure you want to include. - - -Purpose -~~~~~~~ - -.. - The purpose of the procedure, what is the intended outcome, possible - dependencies. - - -Pre-requisites -~~~~~~~~~~~~~~ - -.. - Any tasks to be performed before starting the procedures, checklists, - software requirements, required users and roles, etc. - Optional section. - -You can link to `other resources <https://example.com/>`_. - - -Steps -~~~~~ - -.. - Copy the following step as many times as you need. - - -#. This is the first step of the procedure. - -.. note:: - You can add a note with additional information needed to perform the step. - -You can include commands to be executed, for example: - -.. code-block:: bash - - sudo apt-get install git -y - -You can add an image, for example, a screenshot of the GUI: - -.. figure:: https://www.onap.org/wp-content/uploads/sites/20/2017/02/logo_onap_2017.png - :alt: Example image - :width: 50 % - -.. - Add the result of the step or procedure at the end of the chapter. - If there are verification steps, add them, as well. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst deleted file mode 100644 index d9a895a38..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Architecture -============ - -.. note:: - * This section is used to describe a software component from a high level - view of capability, common usage scenarios, and interactions with other - components required in the usage scenarios. - - * The architecture section is typically: provided in a platform-component - and sdk collections; and referenced from developer and user guides. - - * This note must be removed after content has been added. - - -Capabilities ------------- - - -Usage Scenarios ---------------- - - -Interactions ------------- diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst deleted file mode 100644 index 0fcf3153f..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Build -===== - -.. - * This section is used to describe how a software component is built from - source into something ready for use either in a run-time environment or to - build other components. - - * This section is typically provided for a platform-component, application, - and sdk; and referenced in developer guides. - - -Environment ------------ - -.. - List the tools that need to be installed for building the component. - -Steps ------ - -.. - List the command(s) that need to be executed for the build. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst deleted file mode 100644 index 6d1ec29ba..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Configuration -============= - -.. - * This section is used to describe the options a software component offers - for configuration. - - * Configuration is typically: provided for platform-component and sdk projects; - and referenced in developer and user guides. - - -Pre-requisites --------------- - -.. - List here any dependencies and pre-requisites, e.g. component has to be - deployed, necessary connections have been established, etc. - - -Editing the configuration file ------------------------------- - -.. - Describe the parameters and their values included in the config file. - - -Configuration steps -------------------- - -.. - Add the necessary steps to configure the component, including all options/ - alternatives. - Provide examples (screenshots for GUI, commands for CLI) wherever possible. - -#. Add the configuration. - -Example command: - -.. code-block:: bash - - example command <parameter> - -Example screenshot: - -.. figure:: https://www.onap.org/wp-content/uploads/sites/20/2017/02/logo_onap_2017.png - :alt: Example image - :width: 50 % - -#. Validate the configuration. - -.. code-block:: bash - - example command to validate the configuration - -Output for successful execution: - -.. code-block:: bash - - Example output diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst deleted file mode 100644 index 3a0cd6ad1..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Consumed APIs -============= - -.. - * This section is used to reference APIs that a software component depends on - and uses from other sources. - - * Consumed APIs should be a specific link to the offered APIs from - another component or external source. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst deleted file mode 100644 index 32f8450cc..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Delivery -======== - -.. - * This section is used to describe the delivery of a software component. - For a run-time component, this might be executable images, containers, etc. - For an SDK, this might be libraries. - - * This section is typically provided for a platform-component and sdk; - and referenced in developer and user guides. - -Process -------- -.. - If needed, describe the steps of the delivery pictured on the block diagram. - -.. blockdiag:: - - - blockdiag layers { - orientation = portrait - a -> m; - b -> n; - c -> x; - m -> y; - m -> z; - group l1 { - shape = line; - color = "#07819B"; - x; y; z; - } - group l2 { - shape = line; - color = "#1a3d6f"; - m; n; - } - group l3 { - shape = line; - color = "#5dbeba"; - a; b; c; - } - - } - -Deliverables ------------- - -.. - List the deliverables in the package here. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst deleted file mode 100644 index 66c5f3651..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Design -====== - -.. - * This section is used to describe the internal design structure of a - software component. - - * This section is typically provided: for a platform-component and sdk; and - referenced in developer guides. - - -Design principles ------------------ - -.. - List the basic principles of the component and best practices, as well. - -Static design -------------- - -.. - Description of classes, objects, etc. - -Dynamic view ------------- - -.. - Communication/interaction of objects when implementing the use cases. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst deleted file mode 100644 index deac057b1..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Installation -============ - -.. - * This section is used to describe how a software component is delivered and - installed. - - * This section is typically: provided for a platform-component and - application; and referenced in user guides. - -Preparations ------------- - -.. - e.g. The software must be delivered as described in section Delivery. - -Environment ------------ - -.. - Cloud containers, public cloud, image formats, resource needs. - -Installation ------------- - -Procedure -+++++++++ - -#. Start the installation. - -.. - Include screenshots or specific commands as examples wherever possible. - Add the expected result, as well. - -#. Verify the installation. - -Troubleshooting the installation -++++++++++++++++++++++++++++++++ - -.. - Include both generic troubleshooting steps and ones specific to the - installation steps. - -Upgrade -------- - -.. - If there are any dependencies, mention them here. - Check compatibility between API versions. - -Procedure -+++++++++ - -#. (optional) Backup your data before starting the upgrade. - -.. - Either list the backup steps here or refer to a backup and restore guide (if - it exists). - -#. Start the upgrade. - -#. Verify the success of the upgrade. - -Troubleshooting the upgrade -+++++++++++++++++++++++++++ - -.. - Include both generic troubleshooting steps and ones specific to the upgrade - steps. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst deleted file mode 100644 index 5662acb1f..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Logging -======= - -.. note:: - * This section is used to describe the informational or diagnostic messages emitted from - a software component and the methods or collecting them. - - * This section is typically: provided for a platform-component and sdk; and - referenced in developer and user guides - - * This note must be removed after content has been added. - - -Where to Access Information ---------------------------- - - -Error / Warning Messages ------------------------- diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst deleted file mode 100644 index fbb454a94..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -Offered APIs -============ - -.. - * This section is used to describe the external interfaces offered by a software component - - * This section is typically: provided for a platform-component and sdk; and - referenced in developer guides and api reference manuals. - - * Include links to the generated JSON, HTML, and PDF versions. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst deleted file mode 100644 index 11f38fed9..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 - International License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) ONAP Project and its contributors -.. _release_notes: - -*********************** -<project> Release Notes -*********************** - -.. note:: - * The release note needs to be updated for each ONAP release - * Except the section "Release data" all other sections are optional and should be - applied where applicable - * Only the current release is to be documented in this document - * This note needs to be removed before publishing the final result - -Abstract -======== - -This document provides the release notes for the ``<releasename>`` release. - -Summary -======= - -<Give a high level description of your project with regards to this -specific release> - - -Release Data -============ - -+--------------------------------------+--------------------------------------+ -| **Project** | <project name> | -| | | -+--------------------------------------+--------------------------------------+ -| **Docker images** | make sure you include all docker | -| | images including the | -| | release version | -| | | -+--------------------------------------+--------------------------------------+ -| **Release designation** | <release name followed by version> | -| | | -+--------------------------------------+--------------------------------------+ - - -New features ------------- - -<Describe new features or other new additions> - -**Bug fixes** - -- `CIMAN-65 <https://jira.onap.org/browse/CIMAN-65>`_ and a sentence explaining - what this defect is addressing. - -**Known Issues** - -- `CIMAN-65 <https://jira.onap.org/browse/CIMAN-65>`_ and two to three sentences - explaining what this issue is. - -Deliverables ------------- - -Software Deliverables -~~~~~~~~~~~~~~~~~~~~~ - - -Documentation Deliverables -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -Known Limitations, Issues and Workarounds -========================================= - -System Limitations ------------------- - -Any known system limitations. - - -Known Vulnerabilities ---------------------- - -Results of know vulnerabilities analysis in used modules. - - -Workarounds ------------ - -Any known workarounds. - - -Security Notes --------------- - -**Fixed Security Issues** - -List of security issues fixed in this release including CVEs and OJSI -tickets. - -**Known Security Issues** - -List of new security issues that are left unfixed in this release including -CVEs and OJSI tickets. - - -Test Results -============ -List or refer to any project specific results - - -References -========== - -For more information on the ONAP ``<release name>`` release, please see: - -#. `ONAP Home Page`_ -#. `ONAP Documentation`_ -#. `ONAP Release Downloads`_ -#. `ONAP Wiki Page`_ - - -.. _`ONAP Home Page`: https://www.onap.org -.. _`ONAP Wiki Page`: https://wiki.onap.org -.. _`ONAP Documentation`: https://docs.onap.org -.. _`ONAP Release Downloads`: https://git.onap.org diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst deleted file mode 100644 index 0f6a6cb38..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright 2021 ONAP contributors, Nokia - -User Interfaces -================ - -.. - * This section is used to describe a software component's command line and graphical - user interfaces. - - * This section is typically: provided for a platform-component and application; and - referenced from user guides. - -Graphical user interface (GUI) ------------------------------- - -.. - * Describe how to access the GUI, including user roles/credentials, browser - requirements, etc. - * Describe how to access and use the basic functionalities related to the - given component. Include screenshots wherever possible. - -Command Line Interface (CLI) ----------------------------- - -.. - * Describe how to access the CLI, including user roles/credentials. - * Include the CLI reference here, with descriptions and examples of commands - and parameters. diff --git a/docs/guides/onap-developer/how-to-use-docs/update-review.rst b/docs/guides/onap-developer/how-to-use-docs/update-review.rst deleted file mode 100644 index 3c3a0c037..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/update-review.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _updates-and-review: - -Updates and Review -================== - -Most project owners will need only to concern themselves with their own -project documentation. However, documentation team members and certain -project owners will need to edit and test multiple documentation repositories. - -Updates -------- - -#. Create a JIRA task in the `ONAP JIRA <https://jira.onap.org/>`_ -before you start the updates. The created issue's ID will have to be added to -the commit message. - -.. note:: - The task should be created in the affected project's workspace. The release - should be specified, as well. - -#. If you have not cloned the repository yet, follow the instructions in the -Git guide, section Cloning a repository. If you have done so already, pull the -latest version. -#. Create a local git branch for your changes. -#. Update the required documents in the project repo(s). -#. Build the documentation with tox. -#. Check the output for errors. -#. Add the changed files. -#. Commit your changes. In the commit message, include the issue ID of the -JIRA task, e.g. Issue-ID:DOC-602 -#. Request review with git review. - - -Requesting Reviews ------------------- -#. Go to the gerrit review's page included in the output of the git review -command. -#. In gerrit, add the committers for the given -project. For more information, refer to the `Gerrit guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html#review>`_. - -#. Implement comments by updating your patch, based on -`Updating an existing patch <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html#update-an-existing-patch>`_ -in the Gerrit guide. - -.. note:: - If you already have the branch you need, skip the first 2 steps in the above - guide. diff --git a/docs/guides/onap-developer/index.rst b/docs/guides/onap-developer/index.rst index 4b6f98e91..8158bcb2b 100644 --- a/docs/guides/onap-developer/index.rst +++ b/docs/guides/onap-developer/index.rst @@ -12,10 +12,5 @@ understand or contribute to the ONAP open source. .. toctree:: :maxdepth: 1 - how-to-use-docs/index + contribution/index apiref/index - how-to-use-docs/templates/index - -.. toctree:: - :maxdepth: 1 - :hidden: |
