X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fguides%2Fonap-developer%2Fhow-to-use-docs%2Finclude-documentation.rst;h=91f5309839647f8cd82b01e5cda26d9eaa1bf99e;hb=09767157909e3e105a39b9015c8b21f2f46fd58d;hp=4e76f6149d8d181e9ab93d20f323b659bd645f1e;hpb=de642bf723536e4bd49d5f3db0cabfb341471c77;p=doc.git 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 index 4e76f6149..91f530983 100644 --- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst +++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst @@ -1,9 +1,21 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. 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. Setting Up ========== +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 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. + 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 @@ -14,18 +26,11 @@ below. :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" ]; @@ -36,45 +41,41 @@ below. PA <-- PR [label = "Merge" ]; } +Setup project repositories +-------------------------- +These steps are performed for each project repository that +provides documentation. - -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. +1. 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. +2. 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. Please note that the +reference to your project in *repolist.rst* should be considered +temporary and removed when you reference it from more appropriate +place. + +.. caution:: + + If your access network restricts ssh, you will need to use equivalent + git commands and HTTP Passwords as described `here `_. .. caution:: - If your access network restricts ssh, you will need to use equivalent git commands and - HTTP Passwords as described `here `_. + Don't replace ../ in *git submodule add* with any relative path on + your local file system. It refers to the location of your repository + on the server. .. code-block:: bash @@ -94,19 +95,21 @@ The following sequence will do this over ssh. .. 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. + 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. +3. 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. + See `Templates and Examples`_ below and :ref:`converting-to-rst` + for more information. .. code-block:: bash @@ -133,11 +136,17 @@ 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 + +- 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) +- references: directory/files (solid edges), git submodule + (dotted edges), sphinx toctree (dashed edges) .. graphviz:: @@ -197,28 +206,89 @@ a jenkins verify job, and/or published release documentation including: } +Branches in the DOC Project +--------------------------- + +The DOC project 'master' branch aggregates the 'latest' content +from all ONAP project repositories contributing documentation into a +single tree file structure as described in the previous section. This +branch is continuously integrated and deployed at Read The +Docs as the 'latest' ONAP Documentation by: + +* Jenkins doc-verify-rtd and doc-merge-rtd jobs triggered whenever patches on + contributing repositories contain rst files at or below a top level + 'docs' folder. + +* Subscription in the DOC project to changes in submodule repositories. + These changes appear in the DOC project as commits with title + 'Updated git submodules' when a change to a contributing project + repository is merged. No DOC project code review occurs, only a + submodule repository commit hash is updated to track the head of each + contributing master branch. + +For each ONAP named release the DOC project creates a branch with the +release name. The timing of the release branch is determined by +work needed in the DOC project to prepare the release branch and the +amount of change unrelated to the release in the master branch. +For example contributing projects that create named release branches +early to begin work on the next release and/or contributing projects +to the master that are not yet part of the named release would result +in an earlier named release branch to cleanly separate work to stabilize +a release from other changes in the master branch. + +A named release branch is integrated and deployed at Read The Docs +as the 'named release' by aggregating content from contributing +project repositories. A contributing project repository can +choose one of the following for the 'named release' branch: + +* Remove the contributing project repository submodule and RST + references when not part of the named release. + +* Provide a commit hash or tag for the contributing project master + branch to be used for the life of the release branch or until a + request is submitted to change the commit hash or tag. + +* Provide the commit hash for the head of a named release branch + created in the contributing project repository. This option + may be appropriate if frequent changes are expected over the + life of the named release and work the same way as the continuous + integration and deployment described for the master branch. + +The decision on option for each contributing project repository +can be made or changed before the final release is approved. The +amount of change and expected differences between master and a +named release branch for each repository should drive the choice of +option and timing. + About GIT branches ------------------ GIT is a powerful tool allowing many actions, but without respecting some rules -the GIT structure can be quickly ugly and unmaintaible. +the GIT structure can be quickly hard to maintain. Here are some conventions about GIT branches: + - ALWAYS create a local branch to edit or create any file. This local branch - will be considered as a topic in Gerrit and allow contributors to work at the - same time on the same project. - - 1 feature = 1 branch. In the case of documentation, a new chapter or page about - a new code feature can be considered as a 'doc feature' - - 1 bug = 1 branch. In the case of documentation, a correction on an existing - sentence can be considered as a 'doc bug' + will be considered as a topic in Gerrit and allow contributors to + work at the same time on the same project. + + - 1 feature = 1 branch. In the case of documentation, a new chapter + or page about a new code feature can be considered as a 'doc feature' + + - 1 bug = 1 branch. In the case of documentation, a correction on an + existing sentence can be considered as a 'doc bug' + - the master branch is considered as "unstable", containing new features that will converge to a stable situation for the release date. The day of the release, the repository owner will create a new branch to fix the code and documentation. This will represent the 'stable' code of the release. In this context: + - NEVER push a new feature on a stable branch - - Only bug correction are authorized on a stable branch using cherry pick method + + - Only bug correction are authorized on a stable branch using + cherry pick method .. image:: git_branches.png @@ -229,22 +299,33 @@ Templates and Examples ---------------------- Templates are available that capture the kinds of information useful for different types of projects and provide some examples of -restructured text. We organize templates in the following way to: help authors -understand relationships between documents; keep the user audience context in mind when writing; -and tailor sections for different kinds of projects. +restructured text. We organize templates in the following way to: + + - help authors understand relationships between documents + + - keep the user audience context in mind when writing and + + - tailor sections for different kinds of projects. -**Sections** Represent a certain type of content. A section is **provided** in a repository, to -to describe something about the characteristics, use, capability, etc. of things in that repository. -A section may also be **referenced** from other sections and in other repositories. + +**Sections** Represent a certain type of content. A section +is **provided** in an project repository, to describe something about +the characteristics, use, capability, etc. of things in that repository. +A section may also be **referenced** from other sections and in +other repositories. For example, an API specification provided in a project +repository might be referenced to in a Platform API Reference Guide. The notes in the beginning of each section template provide -additional detail about what is typically covered and where there may be references to the section. +additional detail about what is typically covered and where +there may be references to the section. -**Collections** Are a set of sections that are typically provided for a particular type -of project, repository, guide, reference manual, etc. +**Collections** Are a set of sections that are typically provided +for a particular type of project, repository, guide, reference manual, etc. +For example, a collection for a platform component, an SDK, etc. -You can: browse the template *collections* and *sections* below; show source to look at the Restructured -Text and Sphinx directives used; copy the source either from a browser window -or by downloading the file in raw form from +You can: browse the template *collections* and *sections* below; +show source to look at the Restructured Text and Sphinx directives used; +copy the source either from a browser window or by downloading the +file in raw form from the `gerrit doc repository `_ and then add them to your repository docs folder and index.rst. @@ -272,18 +353,24 @@ 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 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 `_. - -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. +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 `_. + +Each project should: + + - decide what is relevant content + + - determine the best way to create/maintain it in the 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 -------------------- @@ -291,7 +378,7 @@ 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 -`_. +`_. Within a single document, you can reference another section simply by:: @@ -353,12 +440,27 @@ One Project ----------- To test how the documentation renders in HTML, follow these steps: -Install virtual environment. +Install `virtual environment `_ & create one. .. code-block:: bash sudo pip install virtualenv - cd /local/repo/path/to/project + virtualenv onap_docs + +Activate `onap_docs` virtual environment. + +.. code-block:: bash + + source onap_docs/bin/activate + +.. note:: Virtual environment activation has to be performed before attempting to build documentation. + Otherwise, tools necessary for the process might not be available. + +Download a project repository. + +.. code-block:: bash + + git clone http://gerrit.onap.org/r/ Download the doc repository. @@ -371,43 +473,51 @@ Change directory to doc & install requirements. .. code-block:: bash cd doc - sudo pip install -r etc/requirements.txt + pip install -r etc/requirements.txt -Move the conf.py file to your project folder where RST files have been kept: +.. 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. + 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: .. code-block:: bash - mv doc/docs/conf.py / + cp docs/conf.py / -Move the static files to your project folder: +Copy the static files to the project folder where RST files have been kept: .. code-block:: bash - mv docs/_static/ / + cp -r docs/_static/ / Build the documentation from within your project folder: .. code-block:: bash - sphinx-build -b html + sphinx-build -b html / Your documentation shall be built as HTML inside the specified output folder directory. +You can use your Web Browser to open +and check resulting html pages in the output folder. + .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `/docs/`. This is for testing only. Only commit the rst files and related content. .. _building-all-documentation: All Documentation ----------------- -To build the whole documentation under doc/, follow these steps: +To build the all documentation under doc/, follow these steps: -Install virtual environment. +Install `tox `_. .. code-block:: bash - sudo pip install virtualenv - cd /local/repo/path/to/project + sudo pip install tox Download the DOC repository. @@ -415,7 +525,7 @@ Download the DOC repository. git clone http://gerrit.onap.org/r/doc -Update submodules, build documentation using tox & then open using any browser. +Build documentation using tox local environment & then open using any browser. .. code-block:: bash @@ -424,3 +534,18 @@ Update submodules, build documentation using tox & then open using any browser. firefox docs/_build/html/index.html .. note:: Make sure to run `tox -elocal` and not just `tox`. + This updates all submodule repositories that are integrated + by the doc project. + +There are additional tox environment options for checking External +URLs and Spelling. Use the tox environment options below and then +look at the output with the Linux `more` or similar command +scan for output that applies to the files you are validating. + +.. code-block:: bash + + tox -elinkcheck + more < docs/_build/linkcheck/output.txt + + tox -espellcheck + more < docs/_build/spellcheck/output.txt