From 31161eead9fe31dfe11d3ddf0b3dbd8bf0c78c93 Mon Sep 17 00:00:00 2001 From: Andrea Visnyei Date: Fri, 26 Jun 2020 12:58:00 +0200 Subject: Renaming files in documentation guide Renamed files containing introduction, setting up, and converting to RST chapters to reflect content. Issue-ID: DOC-639 Change-Id: I5353fbf52dc635ee43464eb3284c13cedcaf6fa6 Signed-off-by: Andrea Visnyei --- .../how-to-use-docs/converting-formats.rst | 110 ---- .../how-to-use-docs/converting-to-rst.rst | 110 ++++ .../how-to-use-docs/documentation-guide.rst | 142 ------ .../how-to-use-docs/include-documentation.rst | 551 --------------------- .../onap-developer/how-to-use-docs/index.rst | 6 +- .../how-to-use-docs/introduction.rst | 142 ++++++ .../onap-developer/how-to-use-docs/setting-up.rst | 551 +++++++++++++++++++++ 7 files changed, 806 insertions(+), 806 deletions(-) delete mode 100644 docs/guides/onap-developer/how-to-use-docs/converting-formats.rst create mode 100644 docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/include-documentation.rst create mode 100644 docs/guides/onap-developer/how-to-use-docs/introduction.rst create mode 100644 docs/guides/onap-developer/how-to-use-docs/setting-up.rst (limited to 'docs/guides') diff --git a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst deleted file mode 100644 index 56449beb2..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. 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. - -.. _converting-to-rst: - -Converting to RST -================= - -RST format is used for documentation. Other file formats can be converted to RST -with pandoc. - -.. caution:: - - Always check the output text after conversion. For the most common errors, - see section Fixing the converted document. - -Installing pandoc ------------------ - -Pandoc is a powerful document-transformation utility. We'll use it to -do simple conversions, but it is capable of much more. Visit -the `pandoc website `_ for -installation instructions for your platform. - -Converting ----------- - -Using a terminal, navigate to the directory containing the documents -you wish to convert. Next, issue the following command for each file -you'd like to convert: - -:code:`pandoc -s --toc -f -t rst myfile.` - -:code:`-s` tells pandoc to produce a standalone document - -:code:`--toc` tells pandoc to produce a table of contents (optional) - -:code:`-t` tells pandoc to produce reStructuredText output - -:code:`-f` tells pandoc the input format. It should be one of the following: - -+--------------------+---------------------------------------------------------------+ -| Format | Description | -+====================+===============================================================+ -|commonmark | Markdown variant | -+--------------------+---------------------------------------------------------------+ -|docbook | XML-based markup | -+--------------------+---------------------------------------------------------------+ -|docx | Microsoft Word | -+--------------------+---------------------------------------------------------------+ -|epub | Ebook format | -+--------------------+---------------------------------------------------------------+ -|haddock | Doc format produced by tool used on Haskell code | -+--------------------+---------------------------------------------------------------+ -|html | HTML | -+--------------------+---------------------------------------------------------------+ -|json | JSON pandoc AST | -+--------------------+---------------------------------------------------------------+ -|latex | Older typesetting syntax | -+--------------------+---------------------------------------------------------------+ -|markdown | Simple formatting syntax meant to produce HTML | -+--------------------+---------------------------------------------------------------+ -|markdown_github | Github flavored markdown | -+--------------------+---------------------------------------------------------------+ -|markdown_mmd | Multi-markdown flavored markdown | -+--------------------+---------------------------------------------------------------+ -|markdown_phpextra | PHP flavored markdown | -+--------------------+---------------------------------------------------------------+ -|markdown_strict | Markdown with no added pandoc features | -+--------------------+---------------------------------------------------------------+ -|mediawiki | Popular wiki language | -+--------------------+---------------------------------------------------------------+ -|native | Pandoc native Haskell | -+--------------------+---------------------------------------------------------------+ -|odt | Open document text (used by LibreOffice) | -+--------------------+---------------------------------------------------------------+ -|opml | Outline processor markup language | -+--------------------+---------------------------------------------------------------+ -|org | Org mode for Emacs | -+--------------------+---------------------------------------------------------------+ -|rst | reStructuredText | -+--------------------+---------------------------------------------------------------+ -|t2t | Wiki-like formatting syntax | -+--------------------+---------------------------------------------------------------+ -|textile | A formatting syntax similar to RST and markdown | -+--------------------+---------------------------------------------------------------+ -|twiki | Popular wiki formatting syntax | -+--------------------+---------------------------------------------------------------+ - -Fixing the converted document ------------------------------ - -How much you'll need to fix the converted document depends on which file -format you're converting from. Here are a couple of things to watch out -for: - -1. Multi-line titles need to be converted to single line -2. Standalone "**" characters -3. :code:`***bolded***` should be :code:`**bolded**` -4. Mangled tables - -Previewing edits ----------------- - -Web-based -~~~~~~~~~ - -`rst.ninjs.org `_ has an excellent RST previewing -tool that highlights RST errors with line numbers. diff --git a/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst b/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst new file mode 100644 index 000000000..56449beb2 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/converting-to-rst.rst @@ -0,0 +1,110 @@ +.. 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. + +.. _converting-to-rst: + +Converting to RST +================= + +RST format is used for documentation. Other file formats can be converted to RST +with pandoc. + +.. caution:: + + Always check the output text after conversion. For the most common errors, + see section Fixing the converted document. + +Installing pandoc +----------------- + +Pandoc is a powerful document-transformation utility. We'll use it to +do simple conversions, but it is capable of much more. Visit +the `pandoc website `_ for +installation instructions for your platform. + +Converting +---------- + +Using a terminal, navigate to the directory containing the documents +you wish to convert. Next, issue the following command for each file +you'd like to convert: + +:code:`pandoc -s --toc -f -t rst myfile.` + +:code:`-s` tells pandoc to produce a standalone document + +:code:`--toc` tells pandoc to produce a table of contents (optional) + +:code:`-t` tells pandoc to produce reStructuredText output + +:code:`-f` tells pandoc the input format. It should be one of the following: + ++--------------------+---------------------------------------------------------------+ +| Format | Description | ++====================+===============================================================+ +|commonmark | Markdown variant | ++--------------------+---------------------------------------------------------------+ +|docbook | XML-based markup | ++--------------------+---------------------------------------------------------------+ +|docx | Microsoft Word | ++--------------------+---------------------------------------------------------------+ +|epub | Ebook format | ++--------------------+---------------------------------------------------------------+ +|haddock | Doc format produced by tool used on Haskell code | ++--------------------+---------------------------------------------------------------+ +|html | HTML | ++--------------------+---------------------------------------------------------------+ +|json | JSON pandoc AST | ++--------------------+---------------------------------------------------------------+ +|latex | Older typesetting syntax | ++--------------------+---------------------------------------------------------------+ +|markdown | Simple formatting syntax meant to produce HTML | ++--------------------+---------------------------------------------------------------+ +|markdown_github | Github flavored markdown | ++--------------------+---------------------------------------------------------------+ +|markdown_mmd | Multi-markdown flavored markdown | ++--------------------+---------------------------------------------------------------+ +|markdown_phpextra | PHP flavored markdown | ++--------------------+---------------------------------------------------------------+ +|markdown_strict | Markdown with no added pandoc features | ++--------------------+---------------------------------------------------------------+ +|mediawiki | Popular wiki language | ++--------------------+---------------------------------------------------------------+ +|native | Pandoc native Haskell | ++--------------------+---------------------------------------------------------------+ +|odt | Open document text (used by LibreOffice) | ++--------------------+---------------------------------------------------------------+ +|opml | Outline processor markup language | ++--------------------+---------------------------------------------------------------+ +|org | Org mode for Emacs | ++--------------------+---------------------------------------------------------------+ +|rst | reStructuredText | ++--------------------+---------------------------------------------------------------+ +|t2t | Wiki-like formatting syntax | ++--------------------+---------------------------------------------------------------+ +|textile | A formatting syntax similar to RST and markdown | ++--------------------+---------------------------------------------------------------+ +|twiki | Popular wiki formatting syntax | ++--------------------+---------------------------------------------------------------+ + +Fixing the converted document +----------------------------- + +How much you'll need to fix the converted document depends on which file +format you're converting from. Here are a couple of things to watch out +for: + +1. Multi-line titles need to be converted to single line +2. Standalone "**" characters +3. :code:`***bolded***` should be :code:`**bolded**` +4. Mangled tables + +Previewing edits +---------------- + +Web-based +~~~~~~~~~ + +`rst.ninjs.org `_ has an excellent RST previewing +tool that highlights RST errors with line numbers. diff --git a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst deleted file mode 100644 index 70e98ad93..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. 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. - -Introduction -============ -This guide describes how to create documentation for the Open Network -Automation Platform (ONAP). ONAP projects create a variety of -content depending on the nature of the project. For example projects -delivering a platform component may have different types of content than -a project that creates libraries for a software development kit. -The content from each project may be used together as a reference for -that project and/or be used in documents that are tailored to a specific -user audience and tasks they are performing. - -Much of the content in this document is derived from similar -documentation processes used in other Linux Foundation -Projects including OPNFV and Open Daylight. - -Why reStructuredText/Sphinx? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the past, standard documentation methods included ad-hoc Word documents, -PDFs, poorly organized Wikis, and other, often closed, tools like -Adobe FrameMaker. The rise of DevOps, Agile, and Continuous Integration, -however, created a paradigm shift for those who care about documentation -because: - -1. Documentation must be tightly coupled with code/product releases. - In many cases, particularly with open-source products, many different - versions of the same code can be installed in various production - environments. DevOps personnel must have access to the correct version - of documentation. - -2. Resources are often tight, volunteers scarce. With a large software base - like ONAP, a small team of technical writers, even if they are also - developers, cannot keep up with a constantly changing, large code base. - Therefore, those closest to the code should document it as best they can, - and let professional writers edit for style, grammar, and consistency. - -Plain-text formatting syntaxes, such as reStructuredText, Markdown, -and Textile, are a good choice for documentation because: - -a. They are editor agnostic - -b. The source is nearly as easy to read as the rendered text - -c. Documentation can be treated exactly as source code is (e.g. versioned, - diff'ed, associated with commit messages that can be included - in rendered docs) - -d. Shallow learning curve - -The documentation team chose reStructuredText largely because of Sphinx, -a Python-based documentation build system, which uses reStructuredText -natively. In a code base as large as ONAP's, cross-referencing between -component documentation was deemed critical. Sphinx and reStructuredText -have built-in functionality that makes collating and cross-referencing -component documentation easier. - -Which docs should go where? -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Frequently, developers ask where documentation should be created. Should -they always use reStructuredText/Sphinx? Not necessarily. Is the wiki -appropriate for anything at all? Yes. - -It's really up to the development team. Here is a simple rule: - -The more tightly coupled the documentation is to a particular version -of the code, the more likely it is that it should be stored with the -code in reStructuredText. - -The doc team encourages component teams to store as much documentation -as reStructuredText as possible because: - -1. It is easier to edit component documentation for grammar, - spelling, clarity, and consistency. - -2. A consistent formatting syntax across components will allow - flexibility in producing different kinds of output. - -3. It is easier to re-organize the documentation. - -4. Wiki articles tend to grow in size and not maintained making it hard - to find current information. - -Structure ---------- -A top level master document structure is used to organize all -documents created by ONAP projects and this resides in the gerrit doc -repository. Complete documents or guides may reside here and -reference parts of source for documentation from other project -repositories. Other ONAP projects will provide content that -is referenced from this structure. - -:: - - docs - ├── guides - │   ├── onap-developer - │   │   ├── apiref - │   │   ├── architecture - │   │   ├── developing - │   │   ├── how-to-use-docs - │   │   ├── settingup - │   │   ├── tutorials - │   │   └── use-cases - │   ├── onap-provider - │   └── onap-user - ├── release - └── templates -    ├── collections -    └── sections - -Source Files ------------- -All documentation for project repositories should be structured and stored -in or below `/docs/` directory as Restructured Text. -ONAP jenkins jobs that verify and merge documentation are triggered by -RST file changes in the top level docs directory and below. - -Licensing ---------- -All contributions to the ONAP project are done in accordance with the -ONAP licensing requirements. Documentation in ONAP is contributed -in accordance with the `Creative Commons 4.0 `_ license. -All documentation files need to be licensed using the text below. -The license may be applied in the first lines of all contributed RST -files: - -.. code-block:: bash - - .. This work is licensed under a Creative Commons Attribution 4.0 International License. - .. http://creativecommons.org/licenses/by/4.0 - .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL - - These lines will not be rendered in the html and pdf files. - -When there are subsequent, significant contributions to a source file -from a different contributor, a new copyright line may be appended -after the last existing copyright line. 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 deleted file mode 100644 index 91f530983..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst +++ /dev/null @@ -1,551 +0,0 @@ -.. 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 -below. - -.. seqdiag:: - :height: 700 - :width: 1000 - - seqdiag { - 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]; - - 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 -> 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 project repositories --------------------------- -These steps are performed for each project repository that -provides documentation. - -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= - -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:: - - 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 - cd doc - mkdir -p `dirname docs/submodules/$reponame` - git submodule add ../$reponame docs/submodules/$reponame.git - git submodule init docs/submodules/$reponame.git - 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. - - -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. - - -.. code-block:: bash - - git clone ssh://$lfid@gerrit.onap.org:29418/$reponame - cd $reponame - mkdir docs - echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. - - TODO Add files to toctree and delete this header - ------------------------------------------------ - .. 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 - -- file structure: directories (ellipses), files(boxes) - -- references: directory/files (solid edges), git submodule - (dotted edges), sphinx toctree (dashed edges) - -.. graphviz:: - - - digraph docstructure { - size="8,12"; - node [fontname = "helvetica"]; - // Align gerrit repos and docs directories - {rank=same doc aaf aai reponame repoelipse vnfsdk vvp} - {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} - {rank=same releasedocumentindex releaserepolist} - - //Illustrate Gerrit Repos and provide URL/Link for complete repo list - gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ]; - doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"]; - gerrit -> doc; - gerrit -> aaf; - gerrit -> aai; - gerrit -> reponame; - gerrit -> repoelipse; - repoelipse [label=". . . ."]; - gerrit -> vnfsdk; - gerrit -> vvp; - - //Show example of local reponame instance of component info - reponame -> reponamedocsdir; - reponamesm -> reponamedocsdir; - reponamedocsdir [label="docs"]; - reponamedocsdir -> repnamedocsdirindex; - repnamedocsdirindex [label="index.rst", shape=box]; - - //Show detail structure of a portion of doc/docs - doc -> docs; - docs -> confpy; - confpy [label="conf.py",shape=box]; - docs -> masterindex; - masterindex [label="Master\nindex.rst", shape=box]; - docs -> release; - 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"]; - reponamesm [label="reponame.git"]; - - //Example Release document index that references component info provided in other project repo - release -> releasedocumentindex; - releasedocumentindex [label="index.rst", shape=box]; - releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; - 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 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 `_ and -then add them to your repository docs folder and index.rst. - - -Sections -++++++++ - -.. toctree:: - :maxdepth: 1 - :glob: - - ../../../templates/sections/* - - -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 `_. - -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 --------------------- -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:: - - This is a reference to `The title of a section`_ - -Assuming that somewhere else in the same file there a is a section -title something like:: - - The title of a section - ^^^^^^^^^^^^^^^^^^^^^^ - -It's typically better to use ``:ref:`` syntax and labels to provide -links as they work across files and are resilient to sections being -renamed. First, you need to create a label something like:: - - .. _a-label: - - The title of a section - ^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: The underscore (_) before the label is required. - -Then you can reference the section anywhere by simply doing:: - - This is a reference to :ref:`a-label` - -or:: - - This is a reference to :ref:`a section I really liked ` - -.. note:: When using ``:ref:``-style links, you don't need a trailing - underscore (_). - -Because the labels have to be unique, it usually makes sense to prefix -the labels with the project name to help share the label space, e.g., -``sfc-user-guide`` instead of just ``user-guide``. - -Testing -======= - -One RST File ------------- -It is recommended that all rst content is validated by `doc8 `_ standards. -To validate your rst files using doc8, install doc8. - -.. code-block:: bash - - sudo pip install doc8 - -doc8 can now be used to check the rst files. Execute as, - -.. code-block:: bash - - doc8 --ignore D000,D001 - - - -One Project ------------ -To test how the documentation renders in HTML, follow these steps: - -Install `virtual environment `_ & create one. - -.. code-block:: bash - - sudo pip install virtualenv - 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. - -.. code-block:: bash - - git clone http://gerrit.onap.org/r/doc - -Change directory to doc & install requirements. - -.. code-block:: bash - - cd doc - 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. - -Copy the conf.py file to your project folder where RST files have been kept: - -.. code-block:: bash - - cp docs/conf.py / - -Copy the static files to the project folder where RST files have been kept: - -.. code-block:: bash - - cp -r docs/_static/ / - -Build the documentation from within your project folder: - -.. code-block:: bash - - 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 all documentation under doc/, follow these steps: - -Install `tox `_. - -.. code-block:: bash - - sudo pip install tox - -Download the DOC repository. - -.. code-block:: bash - - git clone http://gerrit.onap.org/r/doc - -Build documentation using tox local environment & then open using any browser. - -.. code-block:: bash - - cd doc - tox -elocal - 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 diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst index 90c657501..15ca7f3f2 100644 --- a/docs/guides/onap-developer/how-to-use-docs/index.rst +++ b/docs/guides/onap-developer/how-to-use-docs/index.rst @@ -7,11 +7,11 @@ Creating Documentation .. toctree:: :maxdepth: 2 - documentation-guide + introduction style-guide - include-documentation + setting-up api-swagger-guide - converting-formats + converting-to-rst addendum .. toctree:: diff --git a/docs/guides/onap-developer/how-to-use-docs/introduction.rst b/docs/guides/onap-developer/how-to-use-docs/introduction.rst new file mode 100644 index 000000000..70e98ad93 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/introduction.rst @@ -0,0 +1,142 @@ +.. 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. + +Introduction +============ +This guide describes how to create documentation for the Open Network +Automation Platform (ONAP). ONAP projects create a variety of +content depending on the nature of the project. For example projects +delivering a platform component may have different types of content than +a project that creates libraries for a software development kit. +The content from each project may be used together as a reference for +that project and/or be used in documents that are tailored to a specific +user audience and tasks they are performing. + +Much of the content in this document is derived from similar +documentation processes used in other Linux Foundation +Projects including OPNFV and Open Daylight. + +Why reStructuredText/Sphinx? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the past, standard documentation methods included ad-hoc Word documents, +PDFs, poorly organized Wikis, and other, often closed, tools like +Adobe FrameMaker. The rise of DevOps, Agile, and Continuous Integration, +however, created a paradigm shift for those who care about documentation +because: + +1. Documentation must be tightly coupled with code/product releases. + In many cases, particularly with open-source products, many different + versions of the same code can be installed in various production + environments. DevOps personnel must have access to the correct version + of documentation. + +2. Resources are often tight, volunteers scarce. With a large software base + like ONAP, a small team of technical writers, even if they are also + developers, cannot keep up with a constantly changing, large code base. + Therefore, those closest to the code should document it as best they can, + and let professional writers edit for style, grammar, and consistency. + +Plain-text formatting syntaxes, such as reStructuredText, Markdown, +and Textile, are a good choice for documentation because: + +a. They are editor agnostic + +b. The source is nearly as easy to read as the rendered text + +c. Documentation can be treated exactly as source code is (e.g. versioned, + diff'ed, associated with commit messages that can be included + in rendered docs) + +d. Shallow learning curve + +The documentation team chose reStructuredText largely because of Sphinx, +a Python-based documentation build system, which uses reStructuredText +natively. In a code base as large as ONAP's, cross-referencing between +component documentation was deemed critical. Sphinx and reStructuredText +have built-in functionality that makes collating and cross-referencing +component documentation easier. + +Which docs should go where? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Frequently, developers ask where documentation should be created. Should +they always use reStructuredText/Sphinx? Not necessarily. Is the wiki +appropriate for anything at all? Yes. + +It's really up to the development team. Here is a simple rule: + +The more tightly coupled the documentation is to a particular version +of the code, the more likely it is that it should be stored with the +code in reStructuredText. + +The doc team encourages component teams to store as much documentation +as reStructuredText as possible because: + +1. It is easier to edit component documentation for grammar, + spelling, clarity, and consistency. + +2. A consistent formatting syntax across components will allow + flexibility in producing different kinds of output. + +3. It is easier to re-organize the documentation. + +4. Wiki articles tend to grow in size and not maintained making it hard + to find current information. + +Structure +--------- +A top level master document structure is used to organize all +documents created by ONAP projects and this resides in the gerrit doc +repository. Complete documents or guides may reside here and +reference parts of source for documentation from other project +repositories. Other ONAP projects will provide content that +is referenced from this structure. + +:: + + docs + ├── guides + │   ├── onap-developer + │   │   ├── apiref + │   │   ├── architecture + │   │   ├── developing + │   │   ├── how-to-use-docs + │   │   ├── settingup + │   │   ├── tutorials + │   │   └── use-cases + │   ├── onap-provider + │   └── onap-user + ├── release + └── templates +    ├── collections +    └── sections + +Source Files +------------ +All documentation for project repositories should be structured and stored +in or below `/docs/` directory as Restructured Text. +ONAP jenkins jobs that verify and merge documentation are triggered by +RST file changes in the top level docs directory and below. + +Licensing +--------- +All contributions to the ONAP project are done in accordance with the +ONAP licensing requirements. Documentation in ONAP is contributed +in accordance with the `Creative Commons 4.0 `_ license. +All documentation files need to be licensed using the text below. +The license may be applied in the first lines of all contributed RST +files: + +.. code-block:: bash + + .. This work is licensed under a Creative Commons Attribution 4.0 International License. + .. http://creativecommons.org/licenses/by/4.0 + .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL + + These lines will not be rendered in the html and pdf files. + +When there are subsequent, significant contributions to a source file +from a different contributor, a new copyright line may be appended +after the last existing copyright line. diff --git a/docs/guides/onap-developer/how-to-use-docs/setting-up.rst b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst new file mode 100644 index 000000000..91f530983 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/setting-up.rst @@ -0,0 +1,551 @@ +.. 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 +below. + +.. seqdiag:: + :height: 700 + :width: 1000 + + seqdiag { + 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]; + + 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 -> 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 project repositories +-------------------------- +These steps are performed for each project repository that +provides documentation. + +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= + +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:: + + 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 + cd doc + mkdir -p `dirname docs/submodules/$reponame` + git submodule add ../$reponame docs/submodules/$reponame.git + git submodule init docs/submodules/$reponame.git + 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. + + +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. + + +.. code-block:: bash + + git clone ssh://$lfid@gerrit.onap.org:29418/$reponame + cd $reponame + mkdir docs + echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License. + + TODO Add files to toctree and delete this header + ------------------------------------------------ + .. 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 + +- file structure: directories (ellipses), files(boxes) + +- references: directory/files (solid edges), git submodule + (dotted edges), sphinx toctree (dashed edges) + +.. graphviz:: + + + digraph docstructure { + size="8,12"; + node [fontname = "helvetica"]; + // Align gerrit repos and docs directories + {rank=same doc aaf aai reponame repoelipse vnfsdk vvp} + {rank=same confpy release templates masterindex submodules otherdocdocumentelipse} + {rank=same releasedocumentindex releaserepolist} + + //Illustrate Gerrit Repos and provide URL/Link for complete repo list + gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ]; + doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"]; + gerrit -> doc; + gerrit -> aaf; + gerrit -> aai; + gerrit -> reponame; + gerrit -> repoelipse; + repoelipse [label=". . . ."]; + gerrit -> vnfsdk; + gerrit -> vvp; + + //Show example of local reponame instance of component info + reponame -> reponamedocsdir; + reponamesm -> reponamedocsdir; + reponamedocsdir [label="docs"]; + reponamedocsdir -> repnamedocsdirindex; + repnamedocsdirindex [label="index.rst", shape=box]; + + //Show detail structure of a portion of doc/docs + doc -> docs; + docs -> confpy; + confpy [label="conf.py",shape=box]; + docs -> masterindex; + masterindex [label="Master\nindex.rst", shape=box]; + docs -> release; + 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"]; + reponamesm [label="reponame.git"]; + + //Example Release document index that references component info provided in other project repo + release -> releasedocumentindex; + releasedocumentindex [label="index.rst", shape=box]; + releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"]; + 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 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 `_ and +then add them to your repository docs folder and index.rst. + + +Sections +++++++++ + +.. toctree:: + :maxdepth: 1 + :glob: + + ../../../templates/sections/* + + +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 `_. + +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 +-------------------- +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:: + + This is a reference to `The title of a section`_ + +Assuming that somewhere else in the same file there a is a section +title something like:: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +It's typically better to use ``:ref:`` syntax and labels to provide +links as they work across files and are resilient to sections being +renamed. First, you need to create a label something like:: + + .. _a-label: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: The underscore (_) before the label is required. + +Then you can reference the section anywhere by simply doing:: + + This is a reference to :ref:`a-label` + +or:: + + This is a reference to :ref:`a section I really liked ` + +.. note:: When using ``:ref:``-style links, you don't need a trailing + underscore (_). + +Because the labels have to be unique, it usually makes sense to prefix +the labels with the project name to help share the label space, e.g., +``sfc-user-guide`` instead of just ``user-guide``. + +Testing +======= + +One RST File +------------ +It is recommended that all rst content is validated by `doc8 `_ standards. +To validate your rst files using doc8, install doc8. + +.. code-block:: bash + + sudo pip install doc8 + +doc8 can now be used to check the rst files. Execute as, + +.. code-block:: bash + + doc8 --ignore D000,D001 + + + +One Project +----------- +To test how the documentation renders in HTML, follow these steps: + +Install `virtual environment `_ & create one. + +.. code-block:: bash + + sudo pip install virtualenv + 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. + +.. code-block:: bash + + git clone http://gerrit.onap.org/r/doc + +Change directory to doc & install requirements. + +.. code-block:: bash + + cd doc + 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. + +Copy the conf.py file to your project folder where RST files have been kept: + +.. code-block:: bash + + cp docs/conf.py / + +Copy the static files to the project folder where RST files have been kept: + +.. code-block:: bash + + cp -r docs/_static/ / + +Build the documentation from within your project folder: + +.. code-block:: bash + + 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 all documentation under doc/, follow these steps: + +Install `tox `_. + +.. code-block:: bash + + sudo pip install tox + +Download the DOC repository. + +.. code-block:: bash + + git clone http://gerrit.onap.org/r/doc + +Build documentation using tox local environment & then open using any browser. + +.. code-block:: bash + + cd doc + tox -elocal + 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 -- cgit 1.2.3-korg