diff options
Diffstat (limited to 'docs/how-to-use-docs')
| -rw-r--r-- | docs/how-to-use-docs/Submodules.jpg | bin | 85389 -> 0 bytes | |||
| -rw-r--r-- | docs/how-to-use-docs/addendum.rst | 80 | ||||
| -rw-r--r-- | docs/how-to-use-docs/documentation-guide.rst | 135 | ||||
| -rw-r--r-- | docs/how-to-use-docs/include-documentation.rst | 254 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 12 |
5 files changed, 0 insertions, 481 deletions
diff --git a/docs/how-to-use-docs/Submodules.jpg b/docs/how-to-use-docs/Submodules.jpg Binary files differdeleted file mode 100644 index aeb7956..0000000 --- a/docs/how-to-use-docs/Submodules.jpg +++ /dev/null diff --git a/docs/how-to-use-docs/addendum.rst b/docs/how-to-use-docs/addendum.rst deleted file mode 100644 index 90ab1c7..0000000 --- a/docs/how-to-use-docs/addendum.rst +++ /dev/null @@ -1,80 +0,0 @@ -======== -Addendum -======== - -Index File -========== - -The index file must relatively refence your other rst files in that directory. - -Here is an example index.rst : - -.. code-block:: bash - - ******************* - Documentation Title - ******************* - - .. toctree:: - :numbered: - :maxdepth: 2 - - documentation-example - -Source Files -============ - -Document source files have to be written in reStructuredText format (rst). -Each file would be build as an html page. - -Here is an example source rst file : - -.. code-block:: bash - - ============= - Chapter Title - ============= - - Section Title - ============= - - Subsection Title - ---------------- - - Hello! - -Writing RST Markdown -==================== - -See http://sphinx-doc.org/rest.html . - -**Hint:** -You can add dedicated contents by using 'only' directive with build type -('html' and 'singlehtml') for OPNFV document. But, this is not encouraged to -use since this may make different views. - -.. code-block:: bash - - .. only:: html - This line will be shown only in html version. - -Verify Job ----------- - -The verify job name is **docs-verify-rtd-{branch}**. - -When you send document changes to gerrit, jenkins will create your documents -in HTML formats (normal and single-page) to verify that new document can be -built successfully. Please check the jenkins log and artifact carefully. -You can improve your document even though if the build job succeeded. - -Merge Job ----------- - -The merge job name is **docs-merge-rtd-{branch}**. - -Once the patch is merged, jenkins will automatically trigger building of -the new documentation. This might take about 15 minutes while readthedocs -builds the documentatation. The newly built documentation shall show up -as appropriate placed in docs.opnfv.org/{branch}/path-to-file. - diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst deleted file mode 100644 index fed42a4..0000000 --- a/docs/how-to-use-docs/documentation-guide.rst +++ /dev/null @@ -1,135 +0,0 @@ -=================== -Documentation Guide -=================== - -This page intends to cover the documentation handling for OPNFV. OPNFV projects are expected to create a variety of document types, -according to the nature of the project. Some of these are common to projects that develop/integrate features into the OPNFV platform, e.g. -Installation Instructions and User/Configurations Guides. Other document types may be project-specific. - -.. contents:: - :depth: 3 - :local: - -Getting Started with Documentation for Your Project ---------------------------------------------------- -OPNFV documentation is automated and integrated into our git & gerrit toolchains. - -We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact -store, our WiKi is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation -process for project information, content and deliverables. -Read :ref:`this page <include-documentation>` which elaborates on how documentation is to be included within opnfvdocs. - -Licencing your documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is contributed -in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ and the `SPDX https://spdx.org/>`_ licence. -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. - .. SPDX-License-Identifier: CC-BY-4.0 - .. (c) <optionally add copywriters name> - - These lines will not be rendered in the html and pdf files. - -How and where to store the document content files in your repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All documentation for your project should be structured and stored in the :code:`<repo>/docs/` directory. The documentation toolchain will -look in these directories and be triggered on events in these directories when generating documents. - -Document structure and contribution ------------------------------------ -A general structure is proposed for storing and handling documents that are common across many projects but also for documents that may be -project specific. The documentation is divided into three areas Release, Development and Testing. Templates for these areas can be found -under :code:`opnfvdocs/docs/templates/`. - -Project teams are encouraged to use templates provided by the opnfvdocs project to ensure that there is consistency across the community. -Following representation shows the expected structure: - -:: - - docs/ - ├── development - │ ├── design - │ ├── overview - │ └── requirements - ├── release - │ ├── configguide - │ ├── installation - │ ├── release-notes - │ ├── scenarios - │ │ └── scenario.name - │ └── userguide - └── testing - ├── developer - └── user - - -Release documentation -^^^^^^^^^^^^^^^^^^^^^ -Release documentation is the set of documents that are published for each OPNFV release. These documents are created and developed -following the OPNFV release process and milestones and should reflect the content of the OPNFV release. -These documents have a master index.rst file in the <opnfvdocs> repository and extract content from other repositories. -To provide content into these documents place your <content>.rst files in a directory in your repository that matches the master document -and add a reference to that file in the correct place in the corresponding index.rst file in :code:`opnfvdocs/docs/release/`. - -**Platform Overview**: :code:`opnfvdocs/docs/release/overview` - -- Note this document is not a contribution driven document -- Content for this is prepared by the Marketing team together with the opnfvdocs team - -**Installation Instruction**: :code:`<repo>/docs/release/installation` - -- Folder for documents describing how to deploy each installer and scenario descriptions -- Release notes will be included here <To Confirm> -- Security related documents will be included here -- Note that this document will be compiled into 'OPNFV Installation Instruction' - -**User Guide**: :code:`<repo>/docs/release/userguide` - -- Folder for manuals to use specific features -- Folder for documents describing how to install/configure project specific components and features -- Can be the directory where API reference for project specific features are stored -- Note this document will be compiled into 'OPNFV userguide' - -**Configuration Guide**: :code:`<repo>/docs/release/configguide` - -- Brief introduction to configure OPNFV with its dependencies. - -**Release Notes**: :code:`<repo>/docs/release/release-notes` - -- Changes brought about in the release cycle. -- Include version details. - -Testing documentation -^^^^^^^^^^^^^^^^^^^^^ -Documentation created by test projects can be stored under two different sub directories /user or /developemnt. -Release notes will be stored under <repo>/docs/release/release-notes - -**User documentation**: :code:`<repo>/testing/user/` -Will collect the documentation of the test projects allowing the end user to perform testing towards a OPNFV SUT -e.g. Functest/Yardstick/Vsperf/Storperf/Bottlenecks/Qtip installation/config & user guides. - -**Development documentation**: :code:`<repo>/testing/developent/` -Will collect documentation to explain how to create your own test case and leverage existing testing frameworks e.g. developer guides. - -Development Documentation -^^^^^^^^^^^^^^^^^^^^^^^^^ -Project specific documents such as design documentation, project overview or requirement documentation can be stored under -/docs/development. Links to generated documents will be dislayed under Development Documentaiton section on docs.opnfv.org. -You are encouraged to establish the following basic structure for your project as needed: - -**Requirement Documentation**: :code:`<repo>/docs/development/requirements/` - -- Folder for your requirement documentation -- For details on requirements projects' structures see the `Requirements Projects <https://wiki.opnfv.org/display/PROJ/Requirements+Projects>`_ page. - -**Design Documentation**: :code:`<repo>/docs/development/design` - -- Folder for your upstream design documents (blueprints, development proposals, etc..) - -**Project overview**: :code:`<repo>/docs/development/overview` - -- Folder for any project specific documentation. diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst deleted file mode 100644 index d1a5a62..0000000 --- a/docs/how-to-use-docs/include-documentation.rst +++ /dev/null @@ -1,254 +0,0 @@ -.. _include-documentation: -============================ -Including your Documentation -============================ - -.. contents:: - :depth: 3 - :local: - -In your project repository --------------------------- - -Add your documentation to your repository in the folder structure and -according to the templates listed above. The documentation templates you -will require are available in opnfvdocs/docs/templates/ repository, you should -copy the relevant templates to your <repo>/docs/ directory in your repository. -For instance if you want to document userguide, then your steps shall be -as follows: - -.. code-block:: bash - - git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git - cp -p opnfvdocs/docs/userguide/* <my_repo>/docs/userguide/ - - -You should then add the relevant information to the template that will -explain the documentation. When you are done writing, you can commit -the documentation to the project repository. - -.. code-block:: bash - - git add . - git commit --signoff --all - git review - -In OPNFVDocs Composite Documentation ------------------------------------- - -In toctree -+++++++++++ - -To import project documents from project repositories, we use submodules. - Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows: - -.. image:: Submodules.jpg - :scale: 50 % - -To include your project specific documentation in the composite documentation, -first identify where your project documentation should be included. -Say your project userguide should figure in the ‘OPNFV Userguide’, then: - - -.. code-block:: bash - - vim opnfvdocs/docs/release/userguide.introduction.rst - -This opens the text editor. Identify where you want to add the userguide. -If the userguide is to be added to the toctree, simply include the path to -it, example: - - -.. code-block:: bash - - .. toctree:: - :maxdepth: 1 - - submodules/functest/docs/userguide/index - submodules/bottlenecks/docs/userguide/index - submodules/yardstick/docs/userguide/index - <submodules/path-to-your-file> - -As Hyperlink -++++++++++++ - -It's pretty common to want to reference another location in the -OPNFV 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 -<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_. - -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 <a-label>` - -.. 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``. - -Once you have made these changes you need to push the patch back to -the opnfvdocs team for review and integration. - -.. code-block:: bash - - git add . - git commit --signoff --all - git review - -Be sure to add the project leader of the opnfvdocs project -as a reviewer of the change you just pushed in gerrit. - -'doc8' Validation ------------------ -It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/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 <file> - - -Testing: Build Documentation Locally ------------------------------------- - -Composite OPNFVDOCS documentation -+++++++++++++++++++++++++++++++++ -To build whole documentation under opnfvdocs/, follow these steps: - -Install virtual environment. - -.. code-block:: bash - - sudo pip install virtualenv - cd /local/repo/path/to/project - -Download the OPNFVDOCS repository. - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/opnfvdocs - -Change directory to opnfvdocs & install requirements. - -.. code-block:: bash - - cd opnfvdocs - sudo pip install -r etc/requirements.txt - -Update submodules, build documentation using tox & then open using any browser. - -.. code-block:: bash - - cd opnfvdocs - git submodule update --init - tox -edocs - firefox docs/_build/html/index.html - -.. note:: Make sure to run `tox -edocs` and not just `tox`. - -Individual project documentation -++++++++++++++++++++++++++++++++ -To test how the documentation renders in HTML, follow these steps: - -Install virtual environment. - -.. code-block:: bash - - sudo pip install virtualenv - cd /local/repo/path/to/project - -Download the opnfvdocs repository. - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/opnfvdocs - -Change directory to opnfvdocs & install requirements. - -.. code-block:: bash - - cd opnfvdocs - sudo pip install -r etc/requirements.txt - -Move the conf.py file to your project folder where RST files have been kept: - -.. code-block:: bash - - mv opnfvdocs/docs/conf.py <path-to-your-folder>/ - -Move the static files to your project folder: - -.. code-block:: bash - - mv opnfvdocs/_static/ <path-to-your-folder>/ - -Build the documentation from within your project folder: - -.. code-block:: bash - - sphinx-build -b html <path-to-your-folder> <path-to-output-folder> - -Your documentation shall be built as HTML inside the -specified output folder directory. - -.. 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. - - -Adding your project repository as a submodule --------------------------- - -Clone the opnfvdocs repository and your submodule to .gitmodules following the convention of the file - -.. code-block:: bash - - cd docs/submodules/ - git submodule add https://gerrit.opnfv.org/gerrit/$reponame - git submodule init $reponame/ - git submodule update $reponame/ - git add . - git commit -sv - git review - -Removing a project repository as a submodule --------------------------- - git rm docs/submodules/$reponame - rm -rf .git/modules/$reponame - git config -f .git/config --remove-section submodule.$reponame 2> /dev/null - git add . - git commit -sv - git review - diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst deleted file mode 100644 index 424f471..0000000 --- a/docs/how-to-use-docs/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _documentation-guide: - -=================== -Documentation Guide -=================== - -.. toctree:: - :maxdepth: 2 - - documentation-guide - include-documentation - addendum |
