diff options
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs')
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/CLA_types.png | bin | 0 -> 25736 bytes | |||
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst (renamed from docs/guides/onap-developer/how-to-use-docs/converting-formats.rst) | 8 | ||||
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/index.rst | 7 | ||||
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/introduction.rst (renamed from docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst) | 104 | ||||
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst | 150 | ||||
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/setting-up.rst (renamed from docs/guides/onap-developer/how-to-use-docs/include-documentation.rst) | 76 | ||||
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/style-guide.rst | 25 |
7 files changed, 311 insertions, 59 deletions
diff --git a/docs/guides/onap-developer/how-to-use-docs/CLA_types.png b/docs/guides/onap-developer/how-to-use-docs/CLA_types.png Binary files differnew file mode 100644 index 000000000..d687135af --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/CLA_types.png diff --git a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst index 835a9c5a2..56449beb2 100644 --- a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst +++ b/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst @@ -7,6 +7,14 @@ 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 ----------------- diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst index 90c657501..787b8c17c 100644 --- a/docs/guides/onap-developer/how-to-use-docs/index.rst +++ b/docs/guides/onap-developer/how-to-use-docs/index.rst @@ -7,11 +7,12 @@ Creating Documentation .. toctree:: :maxdepth: 2 - documentation-guide + introduction + setting-up-environment + setting-up style-guide - include-documentation api-swagger-guide - converting-formats + converting-to-rst addendum .. toctree:: diff --git a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guides/onap-developer/how-to-use-docs/introduction.rst index 70e98ad93..ceb2eb0e6 100644 --- a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst +++ b/docs/guides/onap-developer/how-to-use-docs/introduction.rst @@ -17,6 +17,20 @@ 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -96,22 +110,80 @@ is referenced from this structure. :: - docs - ├── guides - │ ├── onap-developer - │ │ ├── apiref - │ │ ├── architecture - │ │ ├── developing - │ │ ├── how-to-use-docs - │ │ ├── settingup - │ │ ├── tutorials - │ │ └── use-cases - │ ├── onap-provider - │ └── onap-user - ├── release - └── templates - ├── collections - └── sections +docs +├── guides +│ ├── active-projects +│ ├── onap-developer +│ │ ├── apiref +│ │ ├── architecture +│ │ │ └── media +│ │ ├── developing +│ │ ├── how-to-use-docs +│ │ ├── tutorials +│ │ └── use-cases +│ ├── 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 +├── templates +│ ├── collections +│ └── sections +└── use-cases + Source Files ------------ diff --git a/docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst b/docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst new file mode 100644 index 000000000..821ee8c68 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst @@ -0,0 +1,150 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2020 Nokia. + +Setting up environment +====================== + +This chapter is based on the `Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`_ +and the `Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_ +in the Linux Foundation Releng Documentation. + +Prerequisites +~~~~~~~~~~~~~ + +Before you start, you should have an LFID account (sign up +`here <https://identity.linuxfoundation.org/>`_). + +Installing git +~~~~~~~~~~~~~~ + +1. Install Git. + + For Debian based systems: + + .. code-block:: bash + + sudo apt-get install git -y + + + For rpm based systems: + + .. code-block:: bash + + sudo dnf install git -y + + + For MacOS systems, install `homebrew <http://brew.sh>`_ and install Git + + .. code-block:: bash + + brew install git + +.. note:: For more information on git, see the `Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`_ in the Linux Foundation Releng Documentation. + +Configure Git +~~~~~~~~~~~~~ + +1. Set the author name or email used to sign off a commit with the following commands. + +.. code-block:: bash + + git config --local user.name "Your Name" + git config --local user.email yourname@example.com + +.. note:: Your name and e-mail address (including capitalization) must match the one you entered when creating your LFID account. + +2. Optionally, change the Git commit editor to your preferred editor, for example, vim. + +.. code-block:: bash + + git config --global core.editor "vim" + +Installing git-review +~~~~~~~~~~~~~~~~~~~~~ + +1. Install git-review. + +.. code-block:: bash + + pip install git-review + +.. note:: If you don’t have pip installed already, follow the `installation documentation <https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py>`_ for pip. + +Setting up gerrit +~~~~~~~~~~~~~~~~~ + +Setting SSH keys +---------------- + +1. Generate SSH keys. + +.. code-block:: bash + + ssh-keygen -t rsa + +Your public key is now available as .ssh/id_rsa.pub in your home folder. + +2. Print the generated key to the terminal and copy it. + +.. code-block:: bash + + cat .ssh/id_rsa.pub + +3. On the project gerrit page, go to Settings. + +.. figure:: https://docs.releng.linuxfoundation.org/en/latest/_images/gerrit-settings.png + :alt: Settings page for your Gerrit account + :width: 50 % + +4. Click **SSH Public Keys** under **Settings**. + +5. Click **Add Key**. + +6. In the **Add SSH Public Key** text box, paste the contents of your **id\_rsa.pub** file and then click **Add**. + +.. figure:: https://docs.releng.linuxfoundation.org/en/latest/_images/gerrit-ssh-keys.png + :alt: Adding your SSH key + :width: 50 % + +Setting up CLA as an individual contributor +------------------------------------------- + +1. Navigate to **Settings** — the gear icon on the upper right corner, and click **Agreements** from the menu on the left: + +.. figure:: https://raw.githubusercontent.com/communitybridge/docs/master/.gitbook/assets/settings-icon.png + +.. figure:: https://raw.githubusercontent.com/communitybridge/docs/master/.gitbook/assets/agreements.png + +2. Click **New Contributor Agreement**. + +.. figure:: https://raw.githubusercontent.com/communitybridge/docs/master/.gitbook/assets/agreement-link.png + +3. New Contributor Agreement types appear: + +.. figure:: https://raw.githubusercontent.com/communitybridge/docs/master/.gitbook/assets/new-contributor-agreement.png + +4. Choose the Individual CLA option. + +.. figure:: CLA_types.png + +5. Click the **Please review the agreement link** and then click the message link that appears: + +.. figure:: https://raw.githubusercontent.com/communitybridge/docs/master/.gitbook/assets/cla-gerrit-icla-proceed-to-sign-cla.png + +6. Sign in to EasyCLA if you are prompted. + +7. Select **Company**. + +.. note:: To contribute to this project, you must be authorized under a signed Contributor License Agreement. You are contributing on behalf of your work for a company. + +If any further prompts appear, follow the steps described at the below links: + +- `If a Confirmation of Association with statement appears <https://docs.linuxfoundation.org/docs/communitybridge/easycla/contributors/contribute-to-a-gerrit-project#if-a-confirmation-of-association-with-statement-appears>`_ +- `If your company has not signed CCLA <https://docs.linuxfoundation.org/docs/communitybridge/easycla/contributors/contribute-to-a-gerrit-project#if-your-company-has-not-signed-ccla>`_ +- `If you are not added to the approved list <https://docs.linuxfoundation.org/docs/communitybridge/easycla/contributors/contribute-to-a-gerrit-project#if-you-are-not-added-to-the-approved-list>`_ +- `If Company is not in the list <https://docs.linuxfoundation.org/docs/communitybridge/easycla/contributors/contribute-to-a-gerrit-project#if-company-is-not-in-the-list>`_ + +8. Complete the form and click **SEND**. + +The CCLA manager signs a Corporate CLA and adds you to the approved list. diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst index 91f530983..cafa4790a 100644 --- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst +++ b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst @@ -295,6 +295,15 @@ release. In this context: 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 @@ -333,24 +342,53 @@ then add them to your repository docs folder and index.rst. Sections ++++++++ -.. toctree:: - :maxdepth: 1 - :glob: - - ../../../templates/sections/* ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|Sections |Description | ++======================================================================================================================+======================================================================================================================================================================================================+ +|`Administration <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/administration.rst>`_ | 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. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Architecture <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/architecture.rst>`_ | 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. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Build <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/build.rst>`_ | 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. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Configuration <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/configuration.rst>`_ | This section is used to describe the options a software component offers for configuration. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Consumed APIs <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/consumedapis.rst>`_ | This section is used to reference APIs that a software component depends on and uses from other sources. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Delivery <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/delivery.rst>`_ | This section is used to describe a software component packaging. For a run-time component this might be executable images, containers, etc. For an SDK this might be libraries. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Design <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/design.rst>`_ | This section is used to describe the internal design structure of a software component. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Human interfaces <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/humaninterfaces.rst>`_ |This section is used to describe a software component's command line and graphical user interfaces. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Installation <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/installation.rst>`_ | This section is used to describe how a software component is acquired and installed. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Logging <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/logging.rst>`_ | This section is used to describe the informational or diagnostic messages emitted from a software component and the methods or collecting them. | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Offered APIs <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/offeredapis.rst>`_ | This section is used to describe the external interfaces offered by a software component | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`Release notes <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/release-notes.rst>`_ | The release note needs to be updated for each ONAP release | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|`VNF reference <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/sections/vnf-reference.rst>`_ | This section is used to describe Virtual Network Function software | +| | | ++----------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Collections +++++++++++ -.. toctree:: - :maxdepth: 1 - :glob: - - ../../../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 @@ -372,6 +410,14 @@ 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. ++------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+ +|Collections |Description | ++==============================================================================================================================+============================================================+ +|`Platform component <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/collections/platform-component.rst>`_ | This collection is used to describe a platform component. | ++------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+ +|`SDK <https://gerrit.onap.org/r/gitweb?p=doc.git;a=blob;f=docs/templates/collections/sdk.rst>`_ | This collection is used to describe an SDK. | ++------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+ + Links and References -------------------- It's pretty common to want to reference another location in the @@ -477,8 +523,8 @@ Change directory to doc & install requirements. .. 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. + 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: 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 index 324688551..dcd1552bf 100644 --- a/docs/guides/onap-developer/how-to-use-docs/style-guide.rst +++ b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst @@ -8,30 +8,6 @@ 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 in later sections of this Developer Documentation Guide. - -.. _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 @@ -141,4 +117,3 @@ Needs Directive * - 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 - |
