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