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=4a7300d16b039c1f1e65da7d5e3798d46215a06b;hpb=082a34dfad1be76bec56865a6bebd2139016aeef;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 4a7300d16..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,12 +1,24 @@ -.. 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 +changes as summarized in the following diagram and description below below. .. seqdiag:: @@ -14,68 +26,57 @@ 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" ]; - PA <-- DR [label = "Merge Notification" ]; + 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 +-------------------------- +These steps are performed for each project repository that +provides documentation. - -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 git clone ssh://$lfid@gerrit.onap.org:29418/doc @@ -86,28 +87,30 @@ The following sequence will do this over ssh. 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. + 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 @@ -120,28 +123,34 @@ to convert or add new content you can update the index and add files under the d ------------------------------------------------ .. 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 + +- 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:: - + digraph docstructure { size="8,12"; node [fontname = "helvetica"]; @@ -156,7 +165,7 @@ a jenkins verify job, and/or published release documentation including: gerrit -> doc; gerrit -> aaf; gerrit -> aai; - gerrit -> reponame; + gerrit -> reponame; gerrit -> repoelipse; repoelipse [label=". . . ."]; gerrit -> vnfsdk; @@ -164,62 +173,159 @@ a jenkins verify job, and/or published release documentation including: //Show example of local reponame instance of component info reponame -> reponamedocsdir; - reponamesm -> reponamedocsdir; + reponamesm -> reponamedocsdir; reponamedocsdir [label="docs"]; - reponamedocsdir -> repnamedocsdirindex; + reponamedocsdir -> repnamedocsdirindex; repnamedocsdirindex [label="index.rst", shape=box]; - //Show detail structure of a portion of doc/docs + //Show detail structure of a portion of doc/docs doc -> docs; - docs -> confpy; + docs -> confpy; confpy [label="conf.py",shape=box]; - docs -> masterindex; + docs -> masterindex; masterindex [label="Master\nindex.rst", shape=box]; docs -> release; - docs -> templates; - docs -> otherdocdocumentelipse; + 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"]; + 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; + release -> releasedocumentindex; releasedocumentindex [label="index.rst", shape=box]; releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; - releaserepolist [label="repolist.rst", shape=box]; + releaserepolist [label="repolist.rst", shape=box]; release -> releaserepolist; releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"]; - + } +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 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' + + - 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 + +.. image:: git_branches.png + Creating Restructured Text ========================== 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. - -**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. +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. + + +**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. @@ -245,20 +351,26 @@ Collections -In addition to these simple templates and examples +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 -------------------- @@ -266,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:: @@ -328,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. @@ -346,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 + +.. 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. -Move the conf.py file to your project folder where RST files have been kept: +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. @@ -390,23 +525,27 @@ Download the DOC repository. git clone http://gerrit.onap.org/r/doc -Change directory to docs & install requirements. +Build documentation using tox local environment & then open using any browser. .. 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 --depth 1 --init - tox -edocs + tox -elocal firefox docs/_build/html/index.html -.. note:: Make sure to run `tox -edocs` and not just `tox`. +.. 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