summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/CLA_types.pngbin0 -> 25736 bytes
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/index.rst3
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/introduction.rst14
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/setting-up-environment.rst150
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/setting-up.rst13
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/style-guide.rst25
6 files changed, 177 insertions, 28 deletions
diff --git a/docs/guides/onap-developer/how-to-use-docs/CLA_types.png b/docs/guides/onap-developer/how-to-use-docs/CLA_types.png
new file mode 100644
index 000000000..d687135af
--- /dev/null
+++ b/docs/guides/onap-developer/how-to-use-docs/CLA_types.png
Binary files differ
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 15ca7f3f2..ddcdcb493 100644
--- a/docs/guides/onap-developer/how-to-use-docs/index.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/index.rst
@@ -9,7 +9,8 @@ Creating Documentation
introduction
style-guide
- setting-up
+ setting-up-environment
+ include-documentation
api-swagger-guide
converting-to-rst
addendum
diff --git a/docs/guides/onap-developer/how-to-use-docs/introduction.rst b/docs/guides/onap-developer/how-to-use-docs/introduction.rst
index ef6ed95ce..ceb2eb0e6 100644
--- a/docs/guides/onap-developer/how-to-use-docs/introduction.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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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/setting-up.rst b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst
index 91f530983..d9f87af51 100644
--- a/docs/guides/onap-developer/how-to-use-docs/setting-up.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
@@ -477,8 +486,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
-