diff options
Diffstat (limited to 'docs/guides/onap-developer')
14 files changed, 642 insertions, 386 deletions
diff --git a/docs/guides/onap-developer/apiref/index.rst b/docs/guides/onap-developer/apiref/index.rst index 7cf6be7d1..9a8970eca 100644 --- a/docs/guides/onap-developer/apiref/index.rst +++ b/docs/guides/onap-developer/apiref/index.rst @@ -39,6 +39,7 @@ Platform Components * :ref:`SDNC - SDN Controller<onap-sdnc-oam:offeredapis>` * :ref:`SO - Service Orchestration<onap-so:offeredapis>` * :ref:`VFC - Virtual Function Controller<onap-vfc-nfvo-lcm:master_index>` +* :ref:`CDS - Controller Design Studio<onap-ccsdk-cds:offeredapis>` Common Services --------------- diff --git a/docs/guides/onap-developer/architecture/media/ONAP-architecture.png b/docs/guides/onap-developer/architecture/media/ONAP-architecture.png Binary files differindex 5f12d955a..0e7c69548 100644 --- a/docs/guides/onap-developer/architecture/media/ONAP-architecture.png +++ b/docs/guides/onap-developer/architecture/media/ONAP-architecture.png diff --git a/docs/guides/onap-developer/developing/index.rst b/docs/guides/onap-developer/developing/index.rst index e4bb6b149..9500ec227 100644 --- a/docs/guides/onap-developer/developing/index.rst +++ b/docs/guides/onap-developer/developing/index.rst @@ -9,302 +9,406 @@ ONAP components and functionalities =================================== -Additional developer level detail is provided for each project below. - -Active and Available Inventory ------------------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -| :ref:`aai aai-common<onap-aai-aai-common:master_index>` -| :ref:`AAI-esr-gui<onap-aai-esr-gui:master_index>` -| :ref:`aai esr-server<onap-aai-esr-server:master_index>` -| :ref:`aai sparky-be<onap-aai-sparky-be:master_index>` -| :ref:`aai event-clientrst<onap-aai-event-client:master_index>` - - -Application Controller ----------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -| :ref:`appc deployment<onap-appc-deployment:master_index>` -| :ref:`appc<onap-appc:master_index>` - -Application Authorization Framework ------------------------------------ - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -| :ref:`aaf authz<onap-aaf-authz:master_index>` -| :ref:`Secret Management Service<onap-aaf-sms:master_index>` - -Command Line Interface ----------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -:ref:`cli<onap-cli:master_index>` - - -Control Loop Automation Management Platform -------------------------------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -:ref:`clamp<onap-clamp:master_index>` - -Common Controller Software Development Kit ------------------------------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: +Here you will find the detailed documentation of projects, +ONAP components and functionalities -| :ref:`ccsdk distribution<onap-ccsdk-distribution:master_index>` -| :ref:`ccsdk dashboard<onap-ccsdk-dashboard:master_index>` -| :ref:`ccsdk platform plugins<onap-ccsdk-platform-plugins:master_index>` -| :ref:`ccsdk apps<onap-ccsdk-apps:master_index>` -| :ref:`ccsdk cds<onap-ccsdk-cds:master_index>` +Project - ONAP Integration +-------------------------- -Data Collection, Analysis, and Events -------------------------------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - :ref:`Integration<onap-integration:master_index>` + - ONAP Integration Project Documentation -:ref:`dcaegen2<onap-dcaegen2:master_index>` +Project - ONAP Modeling +----------------------- -Data Management as a Platform Data Bus Controller -------------------------------------------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 1 - :titlesonly: + * - Document + - Description + * - :ref:`Model<onap-modeling-modelspec:master_index>` + - ONAP Model Specification + * - :ref:`ETSI Catalog<onap-modeling-etsicatalog:master_index>` + - ONAP ETSI Runtime Catalog Documentation -| :ref:`dmaap dbcapi<onap-dmaap-dbcapi:master_index>` -| :ref:`dmaap buscontroller<onap-dmaap-buscontroller:master_index>` -Data Management as a Platform Data Router +AAF - Application Authorization Framework ----------------------------------------- -.. toctree:: - :maxdepth: 1 - :titlesonly: - -:ref:`dmaap datarouter<onap-dmaap-datarouter:master_index>` - -Data Management as a Platform Message Router --------------------------------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -:ref:`dmaap messagerouter messageservice<onap-dmaap-messagerouter-messageservice:master_index>` - -External API Framework ----------------------- - -.. toctree:: - :maxdepth: 2 - :titlesonly: - -:ref:`externalapi nbi<onap-externalapi-nbi:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - (in Maintenance) `AAF (Frankfurt) <https://docs.onap.org/projects/onap-aaf-authz/en/frankfurt/>`_ + - AAF Architecture, APIs and Guides + +AAI - Active and Available Inventory +------------------------------------ + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - :ref:`AAI<onap-aai-aai-common:master_index>` + - AAI Architecture, APIs and Guides + * - (in Maintenance) `ESR GUI (Latest) <https://docs.onap.org/projects/onap-aai-esr-gui/en/latest/>`_ + - External System Registry GUI Documentation + * - (in Maintenance) `ESR Server (Latest) <https://docs.onap.org/projects/onap-aai-esr-server/en/latest/>`_ + - External System Registry Server Documentation + * - (in Maintenance) :ref:`AAI UI<onap-aai-sparky-be:master_index>` + - Sparky - AAI Inventory UI Documentation + +APPC - Application Controller +----------------------------- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - (in Maintenance) `APPC (Frankfurt) <https://docs.onap.org/projects/onap-appc/en/frankfurt/>`_ + - APPC Architecture, APIs and Guides + * - (in Maintenance) `APPC Deployment (Frankfurt) <https://docs.onap.org/projects/onap-appc-deployment/en/frankfurt/>`_ + - APPC Deployment Documentation + +CCSDK - Common Controller Software Development Kit +-------------------------------------------------- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - :ref:`Distribution<onap-ccsdk-distribution:master_index>` + - TOSCA Orchestration Plugin, Directed Graph Support + +CDS - Controller Design Studio +------------------------------ +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Holmes ------- + * - Document + - Description + * - :ref:`CDS<onap-ccsdk-cds:master_index>` + - Controller Design Studio Architecture and Guides (part of CCSDK) -.. toctree:: - :maxdepth: 2 - :titlesonly: +CLAMP - Control Loop Automation Management Platform +--------------------------------------------------- -| :ref:`Alarm Correlation and Analysis<onap-holmes-engine-management:master_index>` -| :ref:`Architecture and APIs<onap-holmes-rule-management:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Integration ------------ + * - Document + - Description + * - :ref:`CLAMP <onap-clamp:master_index>` + - CLAMP Architecture and Guides -.. toctree:: - :maxdepth: 1 - :titlesonly: +CLI - Command Line Interface +---------------------------- -:ref:`integration<onap-integration:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Logging Analytics ------------------ + * - Document + - Description + * - :ref:`CLI <onap-cli:master_index>` + - CLI Documentation -.. toctree:: - :maxdepth: 2 - :titlesonly: +DCAE - Data Collection, Analysis and Events +------------------------------------------- -:ref:`logging-analytics<onap-logging-analytics:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Micro Services Bus ------------------- + * - Document + - Description + * - :ref:`DCAE<onap-dcaegen2:master_index>` + - DCAE Architecture and Guides -.. toctree:: - :maxdepth: 2 - :titlesonly: +DMAAP - Data Management as a Platform +------------------------------------- -:ref:`msb apigateway<onap-msb-apigateway:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - :ref:`Bus Controller<onap-dmaap-buscontroller:master_index>` + - Bus Controller Documentation + * - :ref:`Bus Controller API<onap-dmaap-dbcapi:master_index>` + - Bus Controller API Documentation + * - :ref:`Data Router<onap-dmaap-datarouter:master_index>` + - Data Router Documentation + * - :ref:`Message Router<onap-dmaap-messagerouter-messageservice:master_index>` + - Message Router Documentation + +EXTAPI - External API Framework/NBI +----------------------------------- -:ref:`msb swagger-sdk<onap-msb-swagger-sdk:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 + * - Document + - Description + * - :ref:`EXTAPI<onap-externalapi-nbi:master_index>` + - External API Framework Documentation -Modeling --------- +HOLMES - Holmes Alarm Correlation and Analysis +---------------------------------------------- -.. toctree:: - :maxdepth: 2 - :titlesonly: +.. list-table:: + :widths: 20 80 + :header-rows: 1 -:ref:`modeling modelspec<onap-modeling-modelspec:master_index>` + * - Document + - Description + * - :ref:`HOLMES<onap-holmes-rule-management:master_index>` + - HOLMES Architecture and APIs + * - :ref:`Engine Management<onap-holmes-engine-management:master_index>` + - HOLMES Engine Management Documentation -:ref:`modeling etsicatalog<onap-modeling-etsicatalog:master_index>` +LOGGING - Centralized Logging +----------------------------- -MultiVIM Cloud --------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - (in Maintenance) `LOGGING (Latest) <https://docs.onap.org/projects/onap-logging-analytics/en/latest/>`_ + - ONAP Centralized Logging Documentation -:ref:`multicloud framework<onap-multicloud-framework:master_index>` +MSB - Microservices Bus +----------------------- -Music ------ +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - :ref:`MSB<onap-msb-apigateway:master_index>` + - Microservices Bus Documentation -:ref:`music<onap-music:master_index>` +MULTICLOUD - MultiCloud Framework +--------------------------------- -:ref:`music distributed-kv-store<onap-music-distributed-kv-store:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -ONAP Operations Manager ------------------------ + * - Document + - Description + * - :ref:`MULTICLOUD<onap-multicloud-framework:master_index>` + - MultiCloud Framework Architecture and Guides -.. toctree:: - :maxdepth: 2 - :titlesonly: +MUSIC - ONAP Multi-Site Integration +----------------------------------- -| :ref:`oom<onap-oom:master_index>` -| :ref:`CMPv2 CertService<onap-oom-certservice:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Optimization Framework ----------------------- + * - Document + - Description + * - (in Maintenance) `MUSIC (Frankfurt) <https://docs.onap.org/projects/onap-music/en/frankfurt/>`_ + - MUSIC Architecture and Guides + * - (in Maintenance) `MUSIC KV (Latest) <https://docs.onap.org/projects/onap-music-distributed-kv-store/en/latest/>`_ + - MUSIC Distribute KV Store Documents -.. toctree:: - :maxdepth: 2 - :titlesonly: +OOF - Optimization Framework +---------------------------- -| :ref:`optf has<onap-optf-has:master_index>` -| :ref:`optf osdf<onap-optf-osdf:master_index>` -| :ref:`optf cmso<onap-optf-cmso:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - :ref:`Homing and Allocation<onap-optf-has:master_index>` + - ONAP policy-driven placement optimizing service documentation + * - :ref:`Optimization Service Design Framework<onap-optf-osdf:master_index>` + - Optimization Service Design Framework documentation + * - :ref:`Change Management Schedule Optimization<onap-optf-cmso:master_index>` + - Change Management Schedule Optimization documentation + +OOM - ONAP Operations Manager +----------------------------- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - :ref:`OOM<onap-oom:master_index>` + - ONAP Operations Manager Documentation + * - :ref:`OOM Certification Service<onap-oom-platform-cert-service:master_index>` + - ONAP CMPv2 certification support + +ORAN - Open-RAN Support in ONAP +------------------------------- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Document + - Description + * - :ref:`ORAN<onap-ccsdk-oran:master_index>` + - O-RAN Support in ONAP (part of CCSDK) + +POLICY - Policy Framework +------------------------- -Policy Framework ----------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - :ref:`Policy<onap-policy-parent:master_index>` + - Policy Framework Documentation -:ref:`policy parent<onap-policy-parent:master_index>` +PORTAL - Portal Platform +------------------------ -Portal Platform ---------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - :ref:`Portal<onap-portal:master_index>` + - ONAP Portal Platform Documentation -:ref:`portal<onap-portal:master_index>` +SDC - Service Design & Creation +------------------------------- -Service Design & Creation -------------------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - :ref:`SDC<onap-sdc:master_index>` + - Service Design & Creation Documentation -:ref:`sdc<onap-sdc:master_index>` +SDNC - Software Defined Network Controller +------------------------------------------ -Service Orchestration ---------------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -.. toctree:: - :maxdepth: 2 - :titlesonly: + * - Document + - Description + * - :ref:`SDNC<onap-sdnc-oam:master_index>` + - SDNC Architecture, APIs and Guides -:ref:`so<onap-so:master_index>` +SDNR - Software Defined Network Controller for Radio +---------------------------------------------------- -:ref:`so libs<onap-so-libs:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Software Defined Network Controller ------------------------------------ + * - Document + - Description + * - :ref:`SDN-R<onap-ccsdk-features:master_index>` + - SDN-R Documentation (part of CCSDK) -.. toctree:: - :maxdepth: 2 - :titlesonly: +SO - Service Orchestration +-------------------------- -:ref:`sdnc oam<onap-sdnc-oam:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Software Defined Network Controller for Radio (SDN-R) ------------------------------------------------------ + * - Document + - Description + * - :ref:`SO<onap-so:master_index>` + - Service Orchestration Architecture, APIs and Guides + * - :ref:`SO Libraries<onap-so-libs:master_index>` + - ONAP SO/libs Documentation -.. toctree:: - :maxdepth: 2 - :titlesonly: +UUI - Use Case User Interface +----------------------------- -:ref:`ccsdk features<onap-ccsdk-features:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Use Case User Interface ------------------------ + * - Document + - Description + * - :ref:`UUI<onap-usecase-ui:master_index>` + - Usecase-UI Architecture, APIs and Guides -.. toctree:: - :maxdepth: 2 - :titlesonly: +VFC - Virtual Function Controller +--------------------------------- -:ref:`usecase-ui<onap-usecase-ui:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Virtual Function Controller ---------------------------- + * - Document + - Description + * - :ref:`VF-C<onap-vfc-nfvo-lcm:master_index>` + - Virtual Function Controller Architecture, APIs and Guides -.. toctree:: - :maxdepth: 2 - :titlesonly: +VID - Virtual Infrastructure Deployment +--------------------------------------- -:ref:`vfc nfvo lcm<onap-vfc-nfvo-lcm:master_index>` +.. list-table:: + :widths: 20 80 + :header-rows: 1 -Virtual Infrastructure Deployment ---------------------------------- + * - Document + - Description + * - :ref:`VID<onap-vid:master_index>` + - Virtual Infrastructure Deployment Architecture, APIs and Guides -.. toctree:: - :maxdepth: 2 - :titlesonly: +VNFSDK - VNF Software Development Kit +------------------------------------- +.. list-table:: + :widths: 20 80 + :header-rows: 1 -:ref:`vid<onap-vid:master_index>` + * - Document + - Description + * - :ref:`VnfSDK<onap-vnfsdk-model:master_index>` + - VNF SDK Documentation and User Guides -VNF Software Development Kit ----------------------------- +VVP - VNF Validation Platform +----------------------------- -.. toctree:: - :maxdepth: 2 - :titlesonly: +.. list-table:: + :widths: 20 80 + :header-rows: 1 -:ref:`vnfsdk model<onap-vnfsdk-model:master_index>` + * - Document + - Description + * - :ref:`VVP<onap-vvp-documentation:master_index>` + - VNF Validation Platform Documentation 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 - diff --git a/docs/guides/onap-developer/index.rst b/docs/guides/onap-developer/index.rst index 221f7ca0d..0d2418ba5 100644 --- a/docs/guides/onap-developer/index.rst +++ b/docs/guides/onap-developer/index.rst @@ -12,7 +12,6 @@ understand or contribute to the ONAP open source. .. toctree:: :maxdepth: 1 - tutorials/index how-to-use-docs/index apiref/index diff --git a/docs/guides/onap-developer/tutorials/index.rst b/docs/guides/onap-developer/tutorials/index.rst index 1d090fabe..a181644bc 100644 --- a/docs/guides/onap-developer/tutorials/index.rst +++ b/docs/guides/onap-developer/tutorials/index.rst @@ -5,17 +5,6 @@ Tutorials ========= .. note:: - Until this section is migrated to gerrit/readthedocs, use the links below. + This is an empty document as placeholder for future tutorials. -.. caution:: - The tutorials may refer to earlier versions of software - and have not been certified on the latest Casablanca Release. - -* `Automatically Creating a Netconf Mount in APPC from SDNC <https://wiki.onap.org/x/JYUx>`_ - -* `Clearwater vIMS Onboarding and Instantiation <https://wiki.onap.org/x/RJp9>`_ - -* `How to use SLI-API for SDNC Model, Directed Graph and Adapter prototyping <https://wiki.onap.org/x/0wCW>`_ - -* `Setting up a Nexus Proxy <https://wiki.onap.org/x/_y70>`_ diff --git a/docs/guides/onap-developer/use-cases/index.rst b/docs/guides/onap-developer/use-cases/index.rst deleted file mode 100644 index d9dc0d202..000000000 --- a/docs/guides/onap-developer/use-cases/index.rst +++ /dev/null @@ -1,15 +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. - -Use Cases -========= - -Example uses case descriptions and sequence diagrams illustrating -interactions between platform components. - -.. toctree:: - :maxdepth: 1 - - vfw.rst - volte.rst diff --git a/docs/guides/onap-developer/use-cases/vfw.rst b/docs/guides/onap-developer/use-cases/vfw.rst deleted file mode 100644 index 2f83102a9..000000000 --- a/docs/guides/onap-developer/use-cases/vfw.rst +++ /dev/null @@ -1,74 +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. - -vFirewall Use Case -================== - -Description ------------ - -Onboarding ----------- - - -.. uml:: - - @startuml - title vFW/vFWCL and vDNS VNF Onboarding (R1)\nVFW/vFWCL and vDNS use the same flows but they are separate VNFs/Services - ONAP_User -> SDC : vFW_vDNS resource onboarding (HEAT) - note right : vFWCL (vpg & vfw,vsn)\nvFW (vpg, vfw, vsn)\nvDNS (vpg, vlb,vdns) + DNSScaling (vdns)\ - ONAP_User -> SDC : vFW_vDNS service onboarding - ONAP_User -> SDC : vFW_vDNS distribution - ||| - SDC -> SO : artifact distribution\nNOTIFY,DOWNLOAD,DEPLOY_OK - SDC -> AAI : artifact distribution\nNOTIFY,DOWNLOAD,DEPLOY_OK - SDC -> SDNC : artifact distribution\nNOTIFY,DOWNLOAD,DEPLOY_OK - @enduml - -Instantiation -------------- - -.. uml:: - - @startuml - title vFW vDNS Instantiation (R1)\nvFW and vDNS use the same flows but they are separate VNFs/Services - participant ONAP_User - participant Robot - Participant SDC - Participant VID - Participant SO - ONAP_User -> AAI : populate cloud inventory - note left of AAI: manual via curl or POSTMAN - ||| - ONAP_User -> VID : vFW_vDNS deployment - VID -> SDC : Lookup VNF artifacts - VID -> AAI : Lookup cloud locations, subscriber - VID -> SO : vFW_vDNS Service \nInstantiation\n(base modules) - SO -> AAI : inventory update - VID -> SO : vFW_vDNS VNF Instantiation\n(base modules) - note left of AAI : VFWCL is two VNFs in one service\nso VNF instantiate occurs twice - SO -> AAI : inventory update - ONAP_User -> SDNC : VNF API Preload VNF/VF data - VID -> SO : vFW_vDNS VF Instantiation\n(base modules) - SO -> AAI : inventory update - SO -> SDNC : Generic VNF API\n(assign) - SO -> Multi_VIM : vFW_vDNS Heat template, \nENV file, preload parameters - Multi_VIM -> CloudAPI : vFW_vDNS Heat template,\nENV file, preload parameters or - CloudAPI -> Hypervisor : vFW_vDNS Infrastructure instantiation - Hypervisor -> vFW_vDNS : Nova/Neutron Instantiation - Hypervisor -> CloudAPI : complete - CloudAPI -> Multi_VIM : complete - Multi_VIM -> SO : complete - note right : SO may poll for completion - SO -> SDNC: Generic VNF API\n(activated) - note left : on failure from Openstack SO issues rollback to SDNC - SDNC -> AAI : L3 Network resource update - SO -> VID : complete - note right : VID will poll for completion - ONAP_User -> Robot : run Heat Bridge - Robot -> CloudAPI : retrieve cloud data - Robot -> AAI : Update with cloud data - ||| - @enduml - |
