-.. 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
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::
: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(s)
-----------------------------
-These steps are performed for each project repository that provides documentation.
+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.
+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 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>`_.
-
+ 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
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.
+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.
-
+ See `Templates and Examples`_ below and :ref:`converting-to-rst`
+ for more information.
+
.. code-block:: bash
------------------------------------------------
.. 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"];
gerrit -> doc;
gerrit -> aaf;
gerrit -> aai;
- gerrit -> reponame;
+ gerrit -> reponame;
gerrit -> repoelipse;
repoelipse [label=". . . ."];
gerrit -> vnfsdk;
//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
----------------------
-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;/>`_.
+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 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.
+
+**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
+the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_ and
+then add them to your repository docs folder and index.rst.
+
+
+Sections
+++++++++
.. toctree::
:maxdepth: 1
:glob:
- ../../../templates/**/index
+ ../../../templates/sections/*
-In addition to these simple templates and examples
+
+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 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.
+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 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
--------------------
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.
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.
+ tox -elocal
+ firefox docs/_build/html/index.html
-.. code-block:: bash
+.. note:: Make sure to run `tox -elocal` and not just `tox`.
- cd doc
- git submodule update --init
- tox -edocs
- firefox docs/_build/html/index.html
+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 for
+scanning for output that applies to the files you are validating.
-.. note:: Make sure to run `tox -edocs` and not just `tox`.
+.. code-block:: bash
+ tox -elinkcheck
+ more < docs/_build/linkcheck/output.txt
+ tox -espellcheck
+ more < docs/_build/spellcheck/output.txt
Code Review / doc.git / blobdiff