docs/guide/onap-developer/how-to-use-docs/include-documentation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3
   4 Setting Up
   5 ==========
   6 Some initial steps are required to connect a project with
   7 the master document structure and enable automated publishing of
   8 changes as summarized in the following diagram and described detail
   9 below.
  10
  11 .. seqdiag::
  12
  13    seqdiag {
  14      RD [label = "Read The Docs",                color =lightgreen ];
  15      DA [label = "Doc Project\nAuthor/Committer",   color=lightblue];
  16      DR [label = "Doc Gerrit Repo" ,                     color=pink];
  17      PR [label = "Other Project\nGerrit Repo",          color=pink ];
  18      PA [label = "Other Project\nAuthor/Committer", color=lightblue];
  19
  20      === One time setup doc project only ===
  21      RD  ->   DA [label = "Account Setup" ];
  22      DA  ->   DR [label = "Create initial\nrepository content"];
  23      DA  <<-- DR [label = "Merged" ];
  24      RD  <--  DA [label = "Connect gerrit.onap.org" ];
  25      === For each project & repository containing document source ===
  26      DA  ->   PR [label = "Other Project Contribution to Setup\ndocs directory, index, other initial content" ];
  27      PR  <--  PA [label = "Review/Merge Change" ];
  28      DA  <--  PR [label = "Change Merged" ];
  29      DA  ->   DR [label = "Add Other Project Repo as\nGit submodule in doc project" ];
  30      DA  <--  DR [label = "Change Merged" ];
  31      }
  32
  33
  34
  35 Setup doc project
  36 -----------------
  37 These steps are performed only once for the doc project and include:
  38
  39 (1) creating in the doc repository an initial:
  40         - sphinx master document index
  41         - directory structure aligned with the document structure
  42         - set of test performed in jenkins verify jobs
  43         - configuration for sphinx plugins and redendering of content
  44
  45 (2) establishing an account at readthedocs connected with gerrit.onap.org
  46
  47
  48 Setup other project(s)
  49 ----------------------
  50 These steps are performed for each new project repo (referred to in the
  51 next three code blocks as $newreponame) the master document
  52 in doc repository references and include:
  53
  54 (1) clone, modify, and commit to the other project an initial: docs top
  55 level directory; index.rst; any other intial content.
  56
  57 .. code-block:: bash
  58
  59    git clone ssh://<your_id>@gerrit.onap.org:29418/$newreponame
  60    cd $newreponame
  61    mkdir docs
  62    echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
  63
  64    $newreponame
  65    ============
  66
  67    .. toctree::
  68       :maxdepth: 1
  69
  70    " >  docs/index.rst
  71
  72    git add .
  73    git commit -m "Add RST docs directory and index" -s
  74    git commit --amend
  75    # modify the commit message to comply with ONAP best practices
  76    git review
  77
  78 When the above commit is reviewed and merged complete step 2 before any
  79 new changes are merged into $newreponame.
  80
  81 (2) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the other project and initialized as a git submodule.
  82
  83 .. code-block:: bash
  84
  85    git clone ssh://<your_id>@gerrit.onap.org:29418/doc
  86    # For top level repositories use the following
  87    mkdir doc/docs/submodules/$reponame
  88    # For lower level repositories you may need to make a directory for each node in path
  89
  90    echo "../submodules/$newreponame/index.rst" >> docs/release/index.rst
  91    cd doc/docs/submodules/$reponame
  92
  93    git submodule git https://gerrit.onap.org/r/$reponame
  94    git submodule init $reponame/
  95    git submodule update $reponame/
  96
  97
  98    git add .
  99    git commit -m "Add $newreponame as asubmodule" -s
 100    git commit --amend
 101    # modify the commit message to comply with ONAP best practices
 102    git review
 103
 104
 105
 106 The diagram below illustrates what is accomplished in the setup steps
 107 above from the perspective of a file structure created for local test,
 108 jenkins verify job, and/or merge/publish documentation including:
 109
 110   - all ONAP gerrit project repositories,
 111   - the doc project repository including a master document index.rst, templates, configuration
 112   - the submodules directory where other project repositories and directories/files may be referenced
 113   - newreponame project repository being added and integrated.
 114
 115
 116 .. graphviz::
 117
 118
 119    digraph docstructure {
 120    size="8,12";
 121    node [fontname = "helvetica"];
 122    // Align gerrit repos and docs directories
 123    {rank=same doc aaf aai newreponame repoelipse vnfsdk vvp}
 124    {rank=same confpy release templates masterindex submodules otherdocdocumentelipse}
 125
 126
 127    //Illustrate Gerrit Repos and provide URL/Link for complete repo list
 128    gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ];
 129    gerrit -> doc;
 130    gerrit -> aaf;
 131    gerrit -> aai;
 132    gerrit -> newreponame;
 133    gerrit -> repoelipse;
 134              repoelipse [label=". . . ."];
 135    gerrit -> vnfsdk;
 136    gerrit -> vvp;
 137
 138    //Show example of local newreponame instance of component info
 139    newreponame -> newreponamedocsdir;
 140    newreponamesm -> newreponamedocsdir;
 141                     newreponamedocsdir [label="docs"];
 142    newreponamedocsdir -> newrepodocsdirindex;
 143                          newrepodocsdirindex [label="index.rst", shape=box];
 144
 145    //Show detail structure of a portion of doc/docs
 146    doc  -> docs;
 147    docs -> confpy;
 148            confpy [label="conf.py",shape=box];
 149    docs -> masterindex;
 150            masterindex [label="Master index.rst", shape=box];
 151    docs -> release;
 152    docs -> templates;
 153    docs -> otherdocdocumentelipse;
 154            otherdocdocumentelipse [label="...other\ndocuments"];
 155    docs -> submodules
 156
 157    masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"];
 158
 159    //Show submodule linkage to docs directory
 160    submodules -> newreponamesm [style=dotted,label="git\nsubmodule\nreference"];
 161                  newreponamesm [label="newreponame"];
 162
 163    //Example Release document index that references component info provided in other project repo
 164    release -> releasedocumentindex;
 165               releasedocumentindex [label="index.rst", shape=box];
 166    releasedocumentindex -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
 167
 168    }
 169
 170 THE FOLLOWING SECTION NEEDS TO BE CONSOLIDATED / UPDATED
 171
 172
 173 As a Hyperlink
 174 ++++++++++++++
 175
 176 It's pretty common to want to reference another location in the
 177 ONAP documentation and it's pretty easy to do with
 178 reStructuredText. This is a quick primer, more information is in the
 179 `Sphinx section on Cross-referencing arbitrary locations
 180 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
 181
 182 Within a single document, you can reference another section simply by::
 183
 184    This is a reference to `The title of a section`_
 185
 186 Assuming that somewhere else in the same file there a is a section
 187 title something like::
 188
 189    The title of a section
 190    ^^^^^^^^^^^^^^^^^^^^^^
 191
 192 It's typically better to use ``:ref:`` syntax and labels to provide
 193 links as they work across files and are resilient to sections being
 194 renamed. First, you need to create a label something like::
 195
 196    .. _a-label:
 197
 198    The title of a section
 199    ^^^^^^^^^^^^^^^^^^^^^^
 200
 201 .. note:: The underscore (_) before the label is required.
 202
 203 Then you can reference the section anywhere by simply doing::
 204
 205     This is a reference to :ref:`a-label`
 206
 207 or::
 208
 209     This is a reference to :ref:`a section I really liked <a-label>`
 210
 211 .. note:: When using ``:ref:``-style links, you don't need a trailing
 212           underscore (_).
 213
 214 Because the labels have to be unique, it usually makes sense to prefix
 215 the labels with the project name to help share the label space, e.g.,
 216 ``sfc-user-guide`` instead of just ``user-guide``.
 217
 218
 219 'doc8' Validation
 220 -----------------
 221 It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
 222 To validate your rst files using doc8, install doc8.
 223
 224 .. code-block:: bash
 225
 226    sudo pip install doc8
 227
 228 doc8 can now be used to check the rst files. Execute as,
 229
 230 .. code-block:: bash
 231
 232    doc8 --ignore D000,D001 <file>
 233
 234
 235 Testing: Build Documentation Locally
 236 ------------------------------------
 237
 238 Composite DOC documentation
 239 +++++++++++++++++++++++++++++++++
 240 To build the whole documentation under doc/, follow these steps:
 241
 242 Install virtual environment.
 243
 244 .. code-block:: bash
 245
 246    sudo pip install virtualenv
 247    cd /local/repo/path/to/project
 248
 249 Download the DOC repository.
 250
 251 .. code-block:: bash
 252
 253    git clone http://gerrit.onap.org/r/doc
 254
 255 Change directory to docs & install requirements.
 256
 257 .. code-block:: bash
 258
 259    cd doc
 260    sudo pip install -r etc/requirements.txt
 261
 262 Update submodules, build documentation using tox & then open using any browser.
 263
 264 .. code-block:: bash
 265
 266    cd doc
 267    git submodule update --init
 268    tox -edocs
 269    firefox docs/_build/html/index.html
 270
 271 .. note:: Make sure to run `tox -edocs` and not just `tox`.
 272
 273 Individual project documentation
 274 ++++++++++++++++++++++++++++++++
 275 To test how the documentation renders in HTML, follow these steps:
 276
 277 Install virtual environment.
 278
 279 .. code-block:: bash
 280
 281    sudo pip install virtualenv
 282    cd /local/repo/path/to/project
 283
 284 Download the doc repository.
 285
 286 .. code-block:: bash
 287
 288    git clone http://gerrit.onap.org/r/doc
 289
 290 Change directory to doc & install requirements.
 291
 292 .. code-block:: bash
 293
 294    cd doc
 295    sudo pip install -r etc/requirements.txt
 296
 297 Move the conf.py file to your project folder where RST files have been kept:
 298
 299 .. code-block:: bash
 300
 301    mv doc/docs/conf.py <path-to-your-folder>/
 302
 303 Move the static files to your project folder:
 304
 305 .. code-block:: bash
 306
 307    mv docs/_static/ <path-to-your-folder>/
 308
 309 Build the documentation from within your project folder:
 310
 311 .. code-block:: bash
 312
 313    sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
 314
 315 Your documentation shall be built as HTML inside the
 316 specified output folder directory.
 317
 318 .. 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.
 319
 320
 321 Adding your project repository as a submodule
 322 ---------------------------------------------
 323
 324 Clone the doc repository and add your submodule using the commands below and where $reponame is your repository name.
 325
 326 .. code-block:: bash
 327
 328   cd docs/submodules/
 329   git submodule git https://gerrit.onap.org/r/$reponame
 330   git submodule init $reponame/
 331   git submodule update $reponame/
 332   git add .
 333   git review
 334
 335