diff options
Diffstat (limited to 'docs/guides/onap-developer')
11 files changed, 908 insertions, 0 deletions
diff --git a/docs/guides/onap-developer/architecture/index.rst b/docs/guides/onap-developer/architecture/index.rst new file mode 100644 index 000000000..8d06c4f1f --- /dev/null +++ b/docs/guides/onap-developer/architecture/index.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Architecture +============ + +Platform Components +------------------- + +SDKs +---- + +Dependencies +------------ + diff --git a/docs/guides/onap-developer/developing/index.rst b/docs/guides/onap-developer/developing/index.rst new file mode 100644 index 000000000..1006b2b69 --- /dev/null +++ b/docs/guides/onap-developer/developing/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Developing ONAP +=============== + +Platform Component References +----------------------------- + +Test & Validation Requirements +------------------------------ + diff --git a/docs/guides/onap-developer/how-to-use-docs/addendum.rst b/docs/guides/onap-developer/how-to-use-docs/addendum.rst new file mode 100644 index 000000000..160b18fde --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/addendum.rst @@ -0,0 +1,133 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Addendum +======== + +Index File +---------- + +The index file must relatively reference your other rst files in that directory. + +Here is an example index.rst : + +.. code-block:: bash + + ******************* + Documentation Title + ******************* + + .. toctree:: + :numbered: + :maxdepth: 2 + + documentation-example + +Source Files +------------ + +Document source files have to be written in reStructuredText format (rst). +Each file would be built as an html page. + +Here is an example source rst file : + +.. code-block:: bash + + ============= + Chapter Title + ============= + + Section Title + ============= + + Subsection Title + ---------------- + + Hello! + +Writing RST Markdown +-------------------- + +See http://sphinx-doc.org/rest.html . + +**Hint:** +You can add html content that only appears in html output by using the +'only' directive with build type +('html' and 'singlehtml') for an ONAP document. But, this is not encouraged. + +.. code-block:: bash + + .. only:: html + This line will be shown only in html version. + + +.. index:: single: indices + +Creating Indices +---------------- + +Building an index for your Sphinx project is relatively simple. First, tell Sphinx that +you want it to build an index by adding something like this after your TOC tree: + +.. code-block:: rst + + Indices and Search + ================== + + * :ref:`genindex` + * :ref:`search` + +**Hint:** +Note that search was included here. It works out of the box with any Sphinx project, so you +don't need to do anything except include a reference to it in your :code:`index.rst` file. + +Now, to generate a index entry in your RST, do one of the following: + +.. code-block:: rst + + Some content that requires an :index:`index`. + +or + +.. code-block:: rst + + .. index:: + single: myterm + + Some header containing myterm + ============================= + +In the second case, Sphinx will create a link in the index to the paragraph that follows +the index entry declaration. + +When your project is built, Sphinx will generate an index page populated with the entries +you created in the source RST. + +These are simple cases with simple options. For more information about indexing with Sphinx, +please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_. + + +Jenkins Jobs +------------ + +Verify Job +++++++++++ + +The verify job name is **doc-{stream}-verify-rtd** + +Proposed changes in files in any repository with the path +.. bash + docs/**/*.rst + +will be verified by this job prior to a gerrit code review. +Please check the Jenkins log carefully for warnings. +You can improve your document even if the verify job succeeded. + +Merge Job ++++++++++ + +The merge job name is **doc-{stream}-merge-rtd**. + +When a committer merges a patch that includes files matching the path described above, +the doc project merge job will trigger an update at readthedocs. +This might take about 15 minutes while readthedocs +builds the documentation. diff --git a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst new file mode 100644 index 000000000..5321a18df --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst @@ -0,0 +1,95 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _converting-to-rst: + +Converting to RST +================= + +Installing pandoc +----------------- + +Pandoc is a powerful document-transformation utility. We'll use it to do simple conversions, but it is capable of much more. Visit the `pandoc website <http://pandoc.org/installing.html>`_ for installation instructions for your platform. + +Converting +---------- + +Using a terminal, navigate to the directory containing the documents you wish to convert. Next, issue the following command for each file you'd like to convert: + +:code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>` + +:code:`-s` tells pandoc to produce a standalone document + +:code:`--toc` tells pandoc to produce a table of contents (optional) + +:code:`-t` tells pandoc to produce reStructuredText output + +:code:`-f` tells pandoc the input format. It should be one of the following: + ++--------------------+---------------------------------------------------------------+ +| Format | Description | ++====================+===============================================================+ +|commonmark | Markdown variant | ++--------------------+---------------------------------------------------------------+ +|docbook | XML-based markup | ++--------------------+---------------------------------------------------------------+ +|docx | Microsoft Word | ++--------------------+---------------------------------------------------------------+ +|epub | Ebook format | ++--------------------+---------------------------------------------------------------+ +|haddock | Doc format produced by tool used on Haskell code | ++--------------------+---------------------------------------------------------------+ +|html | HTML | ++--------------------+---------------------------------------------------------------+ +|json | JSON pandoc AST | ++--------------------+---------------------------------------------------------------+ +|latex | Older typesetting syntax | ++--------------------+---------------------------------------------------------------+ +|markdown | Simple formatting syntax meant to produce HTML | ++--------------------+---------------------------------------------------------------+ +|markdown_github | Github flavored markdown | ++--------------------+---------------------------------------------------------------+ +|markdown_mmd | Multi-markdown flavored markdown | ++--------------------+---------------------------------------------------------------+ +|markdown_phpextra | PHP flavored markdown | ++--------------------+---------------------------------------------------------------+ +|markdown_strict | Markdown with no added pandoc features | ++--------------------+---------------------------------------------------------------+ +|mediawiki | Popular wiki language | ++--------------------+---------------------------------------------------------------+ +|native | Pandoc native Haskell | ++--------------------+---------------------------------------------------------------+ +|odt | Open document text (used by LibreOffice) | ++--------------------+---------------------------------------------------------------+ +|opml | Outline processor markup language | ++--------------------+---------------------------------------------------------------+ +|org | Org mode for Emacs | ++--------------------+---------------------------------------------------------------+ +|rst | reStructuredText | ++--------------------+---------------------------------------------------------------+ +|t2t | Wiki-like formatting syntax | ++--------------------+---------------------------------------------------------------+ +|textile | A formatting syntax similar to RST and markdown | ++--------------------+---------------------------------------------------------------+ +|twiki | Popular wiki formatting syntax | ++--------------------+---------------------------------------------------------------+ + +Fixing the converted document +----------------------------- + +How much you'll need to fix the converted document depends on which file format you're converting from. Here are a couple of things to watch out for: + +1. Multi-line titles need to be converted to single line +2. Standalone "**" characters +3. :code:`***bolded***` should be :code:`**bolded**` +4. Mangled tables + +Previewing edits +---------------- + +Web-based +~~~~~~~~~ + +`rst.ninjs.org <http://rst.ninjs.org>`_ has an excellent RST previewing tool that highlights RST errors with line numbers. + + + diff --git a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst new file mode 100644 index 000000000..9586b4b5a --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst @@ -0,0 +1,153 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +Introduction +============ +This guide describes how to create documentation for the Open Network +Automation Platform (ONAP). ONAP projects create a variety of +content depending on the nature of the project. For example projects delivering +a platform component may have different types of content than +a project that creates libraries for a software development kit. +The content from each project may be used together as a reference for that project +and/or be used in documents are tailored to a specific user audience and +task they are performing. + +Much of the content in this document is derived from similar +documentation processes used in other Linux Foundation +Projects including OPNFV and Open Daylight. + + +End to End View +--------------- +ONAP documentation is stored in git repositories, changes are managed +with gerrit reviews, and published documents generated when there is a +change in any source used to build the documentation. + +Authors create source for documents in reStructured Text (RST) that is +rendered to HTML and PDF and published on Readthedocs.io. +The developer Wiki or other web sites can reference these rendered +documents directly allowing projects to easily maintain current release +documentation. + +Why reStructuredText/Sphinx? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the past, standard documentation methods included ad-hoc Word documents, PDFs, +poorly organized Wikis, and other, often closed, tools like Adobe FrameMaker. +The rise of DevOps, Agile, and Continuous Integration, however, created a paradigm +shift for those who care about documentation because: + +1. Documentation must be tightly coupled with code/product releases. In many cases, +particularly with open-source products, many different versions of the same code +can be installed in various production environments. DevOps personnel must have +access to the correct version of documentation. + +2. Resources are often tight, volunteers scarce. With a large software base +like ONAP, a small team of technical writers, even if they are also developers, +cannot keep up with a constantly changing, large code base. Therefore, those closest +to the code should document it as best they can, and let professional writers edit for +style, grammar, and consistency. + +Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile, +are a good choice for documentation because: + +a. They are editor agnostic +b. The source is nearly as easy to read as the rendered text +c. Documentation can be treated exactly as source code is (e.g. versioned, + diff'ed, associated with commit messages that can be included in rendered docs) +d. Shallow learning curve + +The documentation team chose reStructuredText largely because of Sphinx, a Python-based +documentation build system, which uses reStructuredText natively. In a code base +as large as ONAP's, cross-referencing between component documentation was deemed +critical. Sphinx and reStructuredText have built-in functionality that makes +collating and cross-referencing component documentation easier. + +Which docs should go where? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Frequently, developers ask where documentation should be created. Should they always use +reStructuredText/Sphinx? Not necessarily. Is the wiki appropriate for anything at all? Yes. + +It's really up to the development team. Here is a simple rule: + +The more tightly coupled the documentation is to a particular version of the code, +the more likely it is that it should be stored with the code in reStructuredText. + +Two examples on opposite ends of the spectrum: + +Example 1: API documentation is often stored literally as code in the form of formatted +comment sections. This would be an ideal choice for reStructuredText stored in a doc repo. + +Example 2: A high-level document that describes in general how a particular component interacts +with other ONAP components with charts. The wiki would be a better choice for this. + +The doc team encourages component teams to store as much documentation as reStructuredText +as possible because: + +1. The doc team can more easily edit component documentation for grammar, spelling, clarity, and consistency. +2. A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output. +3. The doc team can easily re-organize the documentation. +4. Wiki articles tend to grow stale over time as the people who write them change positions or projects. + +Structure +--------- +A top level master document structure is used to organize all +documents for an ONAP release and this resides in the gerrit doc repository. +Complete documents or guides may reside here and reference parts of +source for documentation from other project repositories +A starting structure is shown below and may change as content is +integrated for each release. Other ONAP projects will provide +content that is referenced from this structure. + +.. index:: master + + +:: + + docs/ + ├── releases + │ ├── major releases + │ ├── projects + │ ├── cryptographic signatures + │ └── references + ├── onap-developer + │ ├── architecture + │ ├── tutorials + │ ├── setting up + │ ├── developing + │ └── documenting + └── onap-users + ├── vf provider + ├── service designer + ├── service administrator + └── platform administrator + + + +Source Files +------------ +All documentation for a project should be structured and stored +in or below `<your_project_repo>/docs/` directory as Restructured Text. +ONAP jenkins jobs that verify and merge documentation are triggered by +RST file changes in the top level docs directory and below. + + +.. index:: licensing + +Licensing +--------- +All contributions to the ONAP project are done in accordance with the +ONAP licensing requirements. Documentation in ONAP is contributed +in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license. +All documentation files need to be licensed using the text below. +The license may be applied in the first lines of all contributed RST +files: + +.. code-block:: bash + + .. This work is licensed under a Creative Commons Attribution 4.0 International License. + .. (c) <optionally add copyrights company name> + + These lines will not be rendered in the html and pdf files. + diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst new file mode 100644 index 000000000..789ad7552 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst @@ -0,0 +1,380 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +Setting Up +========== +Some initial set up is required to connect a project with +the master document structure and enable automated publishing of +changes as summarized in the following diagram and description below +below. + +.. seqdiag:: + :height: 700 + :width: 1000 + + seqdiag { + RD [label = "Read The Docs", color =lightgreen ]; + DA [label = "Doc Project\nAuthor/Committer", color=lightblue]; + DR [label = "Doc Gerrit Repo" , color=pink]; + PR [label = "Other Project\nGerrit Repo", color=pink ]; + PA [label = "Other Project\nAuthor/Committer", color=lightblue]; + + === One time setup doc project only === + RD -> DA [label = "Acquire Account" ]; + DA -> DR [label = "Create initial\n doc repository content"]; + DA <<-- DR [label = "Merge" ]; + RD <-- DA [label = "Connect gerrit.onap.org" ]; + === For each project repository containing document source === + PA -> DR [label = "Add project repo as\ngit submodule" ]; + DR -> DA [label = "Review & Plan to\nIntegrate Content with\nTocTree Structure" ]; + DR <-- DA [label = "Vote +2/Merge" ]; + PA <-- DR [label = "Merge Notification" ]; + PA -> PR [label = "Create in project repo\ntop level directory and index.rst" ]; + PR -> DA [label = "Add as Reviewer" ]; + PR <-- DA [label = "Approve and Integrate" ]; + PA <-- PR [label = "Merge" ]; + } + + + +Setup doc project +----------------- +These steps are performed only once for the doc project and include: + +(1) creating in the doc repository an initial: + - sphinx master document index + - a directory structure aligned with the document structure + - tests performed in jenkins verify jobs + - sphinx configuration + +(2) establishing an account at readthedocs connected with the doc +doc project repo in gerrit.onap.org. + + +Setup project repositories(s) +----------------------------- +These steps are performed for each project repository that provides documentation. + +First let's set two variables that will be used in the subsequent steps. +Set reponame to the project repository you are setting up just as it appears in the +**Project Name** column of the Gerrit projects page. +Set lfid to your Linux Foundation identity that you use to login to gerrit or for git +clone requests over ssh. + +.. code-block:: bash + + reponame= + lfid= + +The next step is to add a directory in the doc project where your project will be included as a +submodule and at least one reference from the doc project to the documentation index in your repository. +The following sequence will do this over ssh. + +.. caution:: + + If your access network restricts ssh, you will need to use equivalent git commands and + HTTP Passwords as described `here <http://wiki.onap.org/x/X4AP>`_. + +.. code-block:: bash + + git clone ssh://$lfid@gerrit.onap.org:29418/doc + cd doc + mkdir -p `dirname docs/submodules/$reponame` + git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame.git + git submodule init docs/submodules/$reponame.git + git submodule update docs/submodules/$reponame.git + + echo " $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst + + git add . + git commit -s + git review + +.. caution:: + Wait for the above change to be merged before any merge to the + project repository that you have just added as a submodule. + If the project repository added as submodule changes before the doc project merge, git may not + automatically update the submodule reference on changes and/or the verify job will + fail in the step below. + + +The last step is to create a docs directory in your repository with an index.rst file. +The following sequence will complete the minimum required over ssh. As you have time +to convert or add new content you can update the index and add files under the docs folder. + +.. hint:: + If you have additional content, you can include it by editing the + index.rst file and/or adding other files before the git commit. + See `Templates and Examples`_ below and :ref:`converting-to-rst` for more information. + + +.. code-block:: bash + + git clone ssh://$lfid@gerrit.onap.org:29418/$reponame + cd $reponame + mkdir docs + echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. + + TODO Add files to toctree and delete this header + ------------------------------------------------ + .. toctree:: + :maxdepth: 1 + + " > docs/index.rst + + git add . + git commit -s + git review + + +The diagram below illustrates what is accomplished in the setup steps +above from the perspective of a file structure created for a local test, +a jenkins verify job, and/or published release documentation including: + - ONAP gerrit project repositories, + - doc project repository master document index.rst, templates, configuration, and other documents + - submodules directory where other project repositories and directories/files are referenced + - file structure: directories (ellipses), files(boxes) + - references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges) + + +.. graphviz:: + + + digraph docstructure { + size="8,12"; + node [fontname = "helvetica"]; + // Align gerrit repos and docs directories + {rank=same doc aaf aai reponame repoelipse vnfsdk vvp} + {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} + {rank=same releasedocumentindex releaserepolist} + + //Illustrate Gerrit Repos and provide URL/Link for complete repo list + gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ]; + doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"]; + gerrit -> doc; + gerrit -> aaf; + gerrit -> aai; + gerrit -> reponame; + gerrit -> repoelipse; + repoelipse [label=". . . ."]; + gerrit -> vnfsdk; + gerrit -> vvp; + + //Show example of local reponame instance of component info + reponame -> reponamedocsdir; + reponamesm -> reponamedocsdir; + reponamedocsdir [label="docs"]; + reponamedocsdir -> repnamedocsdirindex; + repnamedocsdirindex [label="index.rst", shape=box]; + + //Show detail structure of a portion of doc/docs + doc -> docs; + docs -> confpy; + confpy [label="conf.py",shape=box]; + docs -> masterindex; + masterindex [label="Master\nindex.rst", shape=box]; + docs -> release; + docs -> templates; + docs -> otherdocdocumentelipse; + otherdocdocumentelipse [label="...other\ndocuments"]; + docs -> submodules + + masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"]; + + //Show submodule linkage to docs directory + submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"]; + reponamesm [label="reponame.git"]; + + //Example Release document index that references component info provided in other project repo + release -> releasedocumentindex; + releasedocumentindex [label="index.rst", shape=box]; + releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; + releaserepolist [label="repolist.rst", shape=box]; + release -> releaserepolist; + releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"]; + + } + +Creating Restructured Text +========================== + +Templates and Examples +---------------------- +Some templates are available that capture the kinds of information +useful for different types of projects and provide simple examples of +restructured text. +You can: browse the templates below; show source to look at the Restructured +Text and Sphinx directives used; and then copy the source either from a browser window +or by downloading the file in raw form from +the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_. + +.. toctree:: + :maxdepth: 1 + :glob: + + ../../../templates/**/index + +In addition to these simple templates and examples +there are many open source projects (e.g. Open Daylight, Open Stack) +that are using Sphinx and Readthedocs where you may find examples to start with. +Working with project teams we will continue to enhance templates here and +capture frequently asked questions on the developer wiki question +topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_. + +Each project should: decide what is relevant content; determine the +best way to create/maintain it in a CI/CD process; and work with the +documentation team to reference content from the master index and guides. +Consider options including filling in a template, +identifying existing content that can be used as is or +easily converted, and use of Sphinx directives/extensions to automatically +generate restructured text from other source you already have. + +Links and References +-------------------- +It's pretty common to want to reference another location in the +ONAP documentation and it's pretty easy to do with +reStructuredText. This is a quick primer, more information is in the +`Sphinx section on Cross-referencing arbitrary locations +<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_. + +Within a single document, you can reference another section simply by:: + + This is a reference to `The title of a section`_ + +Assuming that somewhere else in the same file there a is a section +title something like:: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +It's typically better to use ``:ref:`` syntax and labels to provide +links as they work across files and are resilient to sections being +renamed. First, you need to create a label something like:: + + .. _a-label: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: The underscore (_) before the label is required. + +Then you can reference the section anywhere by simply doing:: + + This is a reference to :ref:`a-label` + +or:: + + This is a reference to :ref:`a section I really liked <a-label>` + +.. note:: When using ``:ref:``-style links, you don't need a trailing + underscore (_). + +Because the labels have to be unique, it usually makes sense to prefix +the labels with the project name to help share the label space, e.g., +``sfc-user-guide`` instead of just ``user-guide``. + +Testing +======= + +One RST File +------------ +It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards. +To validate your rst files using doc8, install doc8. + +.. code-block:: bash + + sudo pip install doc8 + +doc8 can now be used to check the rst files. Execute as, + +.. code-block:: bash + + doc8 --ignore D000,D001 <file> + + + +One Project +----------- +To test how the documentation renders in HTML, follow these steps: + +Install virtual environment. + +.. code-block:: bash + + sudo pip install virtualenv + cd /local/repo/path/to/project + +Download the doc repository. + +.. code-block:: bash + + git clone http://gerrit.onap.org/r/doc + +Change directory to doc & install requirements. + +.. code-block:: bash + + cd doc + sudo pip install -r etc/requirements.txt + +Move the conf.py file to your project folder where RST files have been kept: + +.. code-block:: bash + + mv doc/docs/conf.py <path-to-your-folder>/ + +Move the static files to your project folder: + +.. code-block:: bash + + mv docs/_static/ <path-to-your-folder>/ + +Build the documentation from within your project folder: + +.. code-block:: bash + + sphinx-build -b html <path-to-your-folder> <path-to-output-folder> + +Your documentation shall be built as HTML inside the +specified output folder directory. + +.. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content. + + +All Documentation +----------------- +To build the whole documentation under doc/, follow these steps: + +Install virtual environment. + +.. code-block:: bash + + sudo pip install virtualenv + cd /local/repo/path/to/project + +Download the DOC repository. + +.. code-block:: bash + + git clone http://gerrit.onap.org/r/doc + +Change directory to docs & install requirements. + +.. code-block:: bash + + cd doc + sudo pip install -r etc/requirements.txt + +Update submodules, build documentation using tox & then open using any browser. + +.. code-block:: bash + + cd doc + git submodule update --init + tox -edocs + firefox docs/_build/html/index.html + +.. note:: Make sure to run `tox -edocs` and not just `tox`. + + + diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst new file mode 100644 index 000000000..cd387df51 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/index.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a + Creative Commons Attribution 4.0 International License. + +Creating Documentation +====================== + +.. toctree:: + :maxdepth: 2 + + documentation-guide + style-guide + include-documentation + converting-formats + addendum 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 new file mode 100644 index 000000000..5d477a99b --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst @@ -0,0 +1,79 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +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 here: <<add links to Documentation process/automated tools sections>> + +.. _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 consistent and readable. Only a few areas are covered below, as we don't want to make it too complex. Try to keep things simple and clear, and you can't go far wrong. + +Don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to this guide than no information at all. ONAP’s Documentation project team will be happy to help you with the prose. + +General guidelines for all documents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- Use standard American English and spelling +- Use consistent terminology +- Write in the active voice, using present simple tense when possible +- Write objective, professional content +- Keep sentences and paragraphs short and clear +- Use a spell checker + +Abbreviations and acronyms +^^^^^^^^^^^^^^^^^^^^^^^^^^ +- Write out the term the first time it appears in the document, immediately followed by the acronym or abbreviation in parenthesis. Then use the acronym in the rest of the document. In diagrams, if space allows, write out the full term. +- Use “an” before an acronym that begins with a vowel sound when spoken aloud; use "a" before an acronym that begins with a consonant sound when spoken aloud. + + Examples: an MSO component, a LAN, an L3-VPN + + +ONAP terms +^^^^^^^^^^ +- AA&I vs AAI: AAI should be used. +- APP-C vs APPC: APPC should be used. +- SDN-C vs SDNC: SDNC should be used. +- Heat vs HEAT: Both are in use. The official website uses "Heat". +- life cycle vs lifecycle or life-cycle: "life cycle" is preferred. +- open source (adjective): capitalize only in titles; avoid "open-source". (Based on prevalence on the web.) +- run-time vs. execution-time (adjective): prefer run-time. Example: "run-time logging of events" +- run time (noun). Example: "logging of events at run time". + +GUI elements +^^^^^^^^^^^^ +- In general, write menu names as they appear in the UI. For example, if a menu or item name is all caps, then write it all caps in the document. + +Headings (Titles) +^^^^^^^^^^^^^^^^^ +- Use brief, but specific, informative titles. Titles should give context when possible. +- Use sentence-style capitalization; do not end with a period or colon. +- Use a gerund to begin section titles. Examples: Configuring, Managing, Starting. +- Use descriptive titles for tables and figures titles. Do not number tables or figures. Do not (in general) add titles for screen shots. + +Tasks +^^^^^ +- Start task titles with an action word. Examples: Create, Add, Validate, Update. +- Use [Optional] at the beginning of an optional step. +- Provide information on the expected outcome of a step, especially when it is not obvious. +- Break down end-to-end tasks into manageable chunks. + diff --git a/docs/guides/onap-developer/index.rst b/docs/guides/onap-developer/index.rst new file mode 100644 index 000000000..4787f52ec --- /dev/null +++ b/docs/guides/onap-developer/index.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _onap_developer_guides: + +ONAP Developer +============== +Describe the kinds of references, tutorials, specifications provided for developers. + +.. toctree:: + :maxdepth: 2 + + architecture/index + tutorials/index + settingup/index + developing/index + how-to-use-docs/index + diff --git a/docs/guides/onap-developer/settingup/index.rst b/docs/guides/onap-developer/settingup/index.rst new file mode 100644 index 000000000..112dc9669 --- /dev/null +++ b/docs/guides/onap-developer/settingup/index.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Setting Up ONAP +=============== + diff --git a/docs/guides/onap-developer/tutorials/index.rst b/docs/guides/onap-developer/tutorials/index.rst new file mode 100644 index 000000000..5864e4d8c --- /dev/null +++ b/docs/guides/onap-developer/tutorials/index.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Tutorials +========= + + + |