diff options
Diffstat (limited to 'docs/guides/onap-developer')
30 files changed, 1131 insertions, 546 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/blueprint-enr.rst b/docs/guides/onap-developer/architecture/blueprint-enr.rst deleted file mode 100644 index a3018a195..000000000 --- a/docs/guides/onap-developer/architecture/blueprint-enr.rst +++ /dev/null @@ -1,100 +0,0 @@ -ONAP Blueprint Enrichment -------------------------- - -The ONAP Beijing release includes four functional enhancements in the -areas of manually triggered scaling, change management, and hardware -platform awareness (HPA). These features required significant community -collaboration as they impact multiple ONAP projects. These features are -applicable to any use case; however, to showcase them in a concrete -manner, they have been incorporated into VoLTE and vCPE blueprints. - -Manually Triggered Scaling -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Scale-out and scale-in are two primary benefits of NFV. Scaling can be -triggered manually (e.g., by a user or OSS/BSS) or automatically via a -policy-driven closed loop. An automatic trigger allows real-time action -without human intervention, reducing costs and improving customer -experience. A manual trigger, on the other hand, is useful to schedule -capacity in anticipation of events such as holiday shopping. An ideal -scaling operation can scale granularly at a virtual function level (VF), -automate VF configuration tasks and manage the load-balancer that may be -in front of the VF instances. In addition to run-time, this capability -also affects service design, as VNF descriptors need to be granular up -to the VF level. - -The Beijing release provides the initial support for these capabilities. -The community has implemented manually triggered scale-out and scale-in -in combination with a specific VNF manager (sVNFM) and demonstrated this -with the VoLTE blueprint. An operator uses the Usecase UI (UUI) project -to trigger a scaleing operation. UUI communicates with the Service -Orchestrator (SO). SO uses the VF-C controller, which in turn instructs -a vendor-provided sVNFM to implement the scale-out action. - -We have also demonstrated a manual process to Scale Out VNFs that use -the Virtual Infrastructure Deployment (VID), the Service Orchestrator -(SO) and the Application Controller (APPC) as a generic VNF Manager. -Currently, the process is for the operator to trigger the Scale Out -action using VID, which will request SO to spin up a new component of -the VNF. Then SO is building the ConfigScaleOut request and sending to -APPC over DMaaP, where APPC picks it up and executes the configuration -scale out action on the requested VNF. - -Change Management -~~~~~~~~~~~~~~~~~ - -NFV will bring with it an era of continuous, incremental changes instead -of periodic step-function software upgrades, in addition to a constant -stream of both PNF and VNF updates and configuration changes. To -automatically deliver these to existing network services, the ONAP -community is creating framework to implement change management -functionality that is independent of any particular network service or -use case. Ideally, change management provides a consistent interface and -mechanisms to manage complex dependencies, different upgrade mechanisms -(in-place vs. scale-out and replace), A/B testing, conflict checking, -pre- and post-change testing, change scheduling, rollbacks, and traffic -draining, redirection and load-balancing. These capabilities impact both -design-time and run-time environments. - -Over the next several releases, the community will enhance change -management capabilities in ONAP, culminating with a full CI/CD flow. -These capabilities can be applied to any use case; however, specifically -for the Beijing release, the vCPE blueprint has been enriched to execute -a predefined workflow to upgrade the virtual gateway VNF by using -Ansible. An operator invokes an upgrade operation through the VID -interface. VID drives SO, which initiates a sequence of steps such as -VNF lock, pre-check, software upgrade, post-check and unlock. Since -virtual gateway is an L3 VNF, the specific operations are carried out by -the SDN-C controller in terms of running the pre-check, post-check and -upgrade through Ansible playbooks. - -Hardware Platform Awareness (HPA) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Many VNFs have specific hardware requirements to achieve their -performance and security goals. These hardware requirements may range -from basic requirements such as number of cores, memory size, and -ephemeral disk size to advanced requirements such as CPU policy (e.g. -dedicate, shared), NUMA, hugepages (size and number), accelerated -vSwitch (e.g DPDK), crypto/compression acceleration, SRIOV-NIC, TPM, SGX -and so on. The Beijing release provides three HPA-related capabilities: - -1. Specification of the VNF hardware platform requirements as a set of - policies. - -2. Discovery of hardware and other platform features supported by cloud - regions. - -3. Selection of the right cloud region and NFV infrastructure flavor by - matching VNF HPA requirements with the discovered platform - capabilities. - -While this functionality is independent of any particular use case, in -the Beijing release, the vCPE use case has been enriched with HPA. An -operator can specify engineering rules for performance sensitive VNFs -through a set of policies. During run-time, SO relies on the ONAP -Optimization Framework (OOF) to enforce these policies via a -placement/scheduling decision. OOF determines the right compute node -flavors for the VNF by querying the above-defined policies. Once a -homing decision is conveyed to SO, SO executes the appropriate workflow -via the appropriate controller. 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..edbf1e219 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 ----------------- @@ -32,53 +40,53 @@ you'd like to convert: :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 | -+--------------------+---------------------------------------------------------------+ ++--------------------+----------------------------------------------------+ +| 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 ----------------------------- @@ -98,5 +106,5 @@ Previewing edits Web-based ~~~~~~~~~ -`rst.ninjs.org <http://rst.ninjs.org>`_ has an excellent RST previewing -tool that highlights RST errors with line numbers. +`Online Sphinx editor <https://livesphinx.herokuapp.com/>`_ is a RST previewing +tool. 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..2e7e47acf 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,13 @@ Creating Documentation .. toctree:: :maxdepth: 2 - documentation-guide + introduction + setting-up + setting-up-environment style-guide - include-documentation api-swagger-guide - converting-formats + templates + 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..17dee9fda 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 @@ -67,8 +43,8 @@ Abbreviations and acronyms + Examples: an MSO component, a LAN, an L3-VPN -ONAP terms -^^^^^^^^^^ +ONAP terminology +^^^^^^^^^^^^^^^^ - AA&I vs AAI: AAI should be used. - APP-C vs APPC: APPC should be used. @@ -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/how-to-use-docs/templates.rst b/docs/guides/onap-developer/how-to-use-docs/templates.rst new file mode 100644 index 000000000..73b60666b --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates.rst @@ -0,0 +1,24 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2020 ONAP community + +Templates +========= + +This section provides templates for the projects + +Sections +-------- + +.. toctree:: + :maxdepth: 1 + + templates/collections/platform-component.rst + templates/collections/sdk.rst + +Release notes +------------- +.. toctree:: + :maxdepth: 1 + + templates/sections/release-notes.rst 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 new file mode 100644 index 000000000..3cde22948 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst @@ -0,0 +1,23 @@ +.. 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/humaninterfaces.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 new file mode 100644 index 000000000..83fbbe2ee --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/collections/sdk.rst @@ -0,0 +1,17 @@ +.. 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/sections/administration.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst new file mode 100644 index 000000000..94a740718 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst @@ -0,0 +1,24 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Administration +============== + + +.. note:: + * 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. + + +Processes +--------- + + +Actions +------- 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 new file mode 100644 index 000000000..8daa0d3bc --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +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 new file mode 100644 index 000000000..99a061c24 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Build +===== + +.. note:: + * 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. + + * This note must be removed after content has been added. + + +Environment +----------- + + +Steps +----- 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 new file mode 100644 index 000000000..085f9c667 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +============= + +.. note:: + * 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. + + * This note must be removed after content has been added. + + + +Example ... + +You can provide the following in ``basic.conf`` + +``host=ADDRESS`` + The address of the host + +``port=PORT`` + The port used for signaling + + Optional. Default: ``8080`` 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 new file mode 100644 index 000000000..c2af4c20e --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Consumed APIs +============= + +.. note:: + * 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. + + * This note must be removed after content has been added. + + 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 new file mode 100644 index 000000000..f3f083a73 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst @@ -0,0 +1,44 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Delivery +======== + +.. note:: + * 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. + + * 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. + +Example use of a block diagram. + +.. blockdiag:: + + + blockdiag layers { + orientation = portrait + a -> m; + b -> n; + c -> x; + m -> y; + m -> z; + group l1 { + color = blue; + x; y; z; + } + group l2 { + color = yellow; + m; n; + } + group l3 { + color = orange; + a; b; c; + } + + } + + 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 new file mode 100644 index 000000000..f173a2fb5 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Design +====== + +.. note:: + * 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. + + * This note must be removed after content has been added. diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/humaninterfaces.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/humaninterfaces.rst new file mode 100644 index 000000000..429284608 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/humaninterfaces.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Human Interfaces +================ + +.. note:: + * 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. + + * This note must be removed after content has been added. + + + 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 new file mode 100644 index 000000000..be64a63bb --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst @@ -0,0 +1,20 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation +============ + +.. note:: + * This section is used to describe how a software component is acquired and installed. + + * This section is typically: provided for a platform-component and application; and + referenced in user guides. + + * This note must be removed after content has been added. + +Environment +----------- + + +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 new file mode 100644 index 000000000..39eabfba7 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst @@ -0,0 +1,22 @@ +.. 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 new file mode 100644 index 000000000..23504c1da --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Offered APIs +============ + +.. note:: + * 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. + + * This note must be removed after content has been added. + 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 new file mode 100644 index 000000000..11f38fed9 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst @@ -0,0 +1,127 @@ +.. 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/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 deleted file mode 100644 index 1d090fabe..000000000 --- a/docs/guides/onap-developer/tutorials/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. - -Tutorials -========= - -.. note:: - Until this section is migrated to gerrit/readthedocs, use the links below. - -.. 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 - |
