VNFRQTS <> Documentation Project Workflow

This project generates documentation (not code)  for use by other ONAP projects and for publication by ONAP. 

VNFRQTS Project in relation to Documentation Project

The documentation project compiles and publishes the final version of the documentation source material produced by this project.

The basic process to compile the documents at ONAP is to use the Sphinx / ReadThe Docs tool  driven by a Jenkins job to pull the latest files from the repos and generate the output document format. The Documentation project will  maintain the Sphinx/ Jenkins configs to generate the documents and have them hosted at onap.readthedocs.io. The VNF RQTS project is mainly responsible for generating the files in the VNF RQTS repos.  Sphinx can accept documents in either reStructuredTexT (.rst) or Markdown (.md, .markdown, .txt, .text) formats. An example with ReStructuredTxT and corresponding html generated by Sphinx is provided by the documentation project. An example of developing and contribution markdown source documents is also available here. 

Open

Essentially, ONAP will treat the requirements documentation as code. To compile the complete documents, The documentation project will maintain a Jenkins job that:

-          Is triggered by a change in /doc project files or any other project/doc/files referenced in the index toctree(s)

-          Collects the referenced source files into a hierarchy within the VM file systems running the Jenkins Job 

-          Run Sphinx makefile to verify relationships and build html, pdf, epub versions

-          If successful issues a RestAPI (webhook api at Readthedocs) to pull the new build into http://onap.readthedocs.io

The requirements documentation must follow the rules defined by the Documentation project: http://onap.readthedocs.io/en/latest/guides/onap-developer/how-to-use-docs/include-documentation.html#testing

- compliant with Doc8 https://pypi.python.org/pypi/doc8

Project Responsibilities 

The VNF Requirements project defines:

• Where our documentation needs to fit in the overall documentation structure, as well as

• The structure of our documents (We need to clarify what a Document is)
  
  

  • Chapters

  • .rst files

    • start with assuming one chapter per .rst file

    • if chapters too big then chunk smaller by document sections

    • objective is to keep manage-ably sized, coherent chunks of content together for review/commit purposes  

  • The structure of our documents should be reflected as within the repo structure of our project.

    • directories

      • all the .rst files of one document in one directory

      • only one document per directory