documentation
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
documentation [2015/12/10 12:55] Ryota Mibu |
documentation [2016/03/16 00:00] (current) Aric Gardner |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| OPNFV documentation is automated and integrated into our git & gerrit toolchains. | 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 artfecact store, our WiKi is able to integrate these rendered documents directly allowing projects to use the revision controlled documentation process for project information, content and deliverables. | + | 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. |
| ===== Enabling the documentation toolchain in your project ===== | ===== Enabling the documentation toolchain in your project ===== | ||
| Line 10: | Line 10: | ||
| The linked page above is written completely in generated artifacts, check the source to see how to do it yourself! | The linked page above is written completely in generated artifacts, check the source to see how to do it yourself! | ||
| - | ==== How and where to store the document content files in your repository. ==== | + | ===== 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 [[http://creativecommons.org/licenses/by/4.0|Creative Commons 4.0]] licence. | ||
| + | All documentation files need to be licensed using the creative commons licence. The following example may be applied in the first lines of all contributed RST files: | ||
| + | |||
| + | .. This work is licensed under a Creative Commons Attribution 4.0 International License. | ||
| + | .. http://creativecommons.org/licenses/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 ''<repo>/docs/'' directory. The documentation toolchain will look in these directories and be triggered on events in these directories when generating documents. | ||
| + | |||
| + | ==== Project documentation ==== | ||
| While many of your documents may be specific to your work there is a general structure proposed for storing and handling documents that are common across many projects. You are encouraged to establish the following basic structure for your project as needed: | While many of your documents may be specific to your work there is a general structure proposed for storing and handling documents that are common across many projects. You are encouraged to establish the following basic structure for your project as needed: | ||
| - | * Requirement Documentation: <repo>/docs/requirements/ | + | * Requirement Documentation: ''<repo>/docs/requirements/'' |
| - | * Should be where your requirement documentation is created | + | * Should be the folder for your requirement documentation |
| - | * Design Documentation: <repo>/docs/design/ | + | * Design Documentation: ''<repo>/docs/design/'' |
| - | * Should be where your upstream design documents (blueprints, development proposals, etc..) are stored | + | * Should be the folder for your upstream design documents (blueprints, development proposals, etc..) |
| - | * For details on requirements projects structures see the [[requirements_projects|Requirements Projects]] page | + | * For details on requirements projects' structures see the [[requirements_projects|Requirements Projects]] page |
| - | * Release Documentation: <repo>/docs/release/ | + | ==== 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 timelines and should reflect the content of the OPNFV release. | ||
| + | |||
| + | For release documents specific to a project, the documentation should be created in the projects' release directory. | ||
| + | |||
| + | * Release Documentation: ''<repo>/docs/release-notes/'' | ||
| * Should be the directory where any release specific documentation (release notes) is produced | * Should be the directory where any release specific documentation (release notes) is produced | ||
| - | * Platform Overview: <project dir>/docs/platformoverview | + | Release documents that represent the OPNFV release as a whole have a specific structure and content collation method. 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 master //index.rst// file in ''<opnfvdocs>''. |
| - | * Should be where overview of a release deliverable is placed | + | |
| - | * Note this document will be compiled into OPNFVDOCS 'paltformoverview' | + | |
| - | * Installation Manual: <project dir>/docs/configguide | + | * Platform Overview: ''<repo>/docs/platformoverview'' |
| - | * Should be where manuals to install/configure project specific components and features are stored | + | * Should be the folder for the overview of a release deliverable |
| + | * Note this document will be compiled into OPNFVDOCS 'platformoverview' | ||
| + | |||
| + | * [[documentation:configguide|Installation and Configuration Guide]]: ''<repo>/docs/configguide'' | ||
| + | * Should be the folder for manuals to install/configure project specific components and features | ||
| * Guides to validate project specific features can be included | * Guides to validate project specific features can be included | ||
| * Note this document will be compiled into OPNFVDOCS 'configguide' | * Note this document will be compiled into OPNFVDOCS 'configguide' | ||
| + | * NOTE: see [[documentation:configguide]]. | ||
| - | * User Guide: <project dir>/docs/userguide | + | * [[documentation:userguide|User Guide]]: ''<repo>/docs/userguide'' |
| - | * Should be where manuals to use specific features are stored | + | * Should be the folder for manuals to use specific features |
| * Can be the directory where API reference for project specific features are stored | * Can be the directory where API reference for project specific features are stored | ||
| - | * Can be where typical scenario is stored as an example | + | * Can be the place for sotring typical scenario as an example |
| * Note this document will be compiled into OPNFVDOCS 'userguide' | * Note this document will be compiled into OPNFVDOCS 'userguide' | ||
| - | |||
| - | Any other documentation can be created under <repo>/docs/ with directory name excluding names in this list. | ||
| - | |||
| ===== Documentation projects ===== | ===== Documentation projects ===== | ||
| [[documentation:opnfvdocs|OPNFV Documentation Project]] | [[documentation:opnfvdocs|OPNFV Documentation Project]] | ||
documentation.1449752125.txt.gz · Last modified: 2015/12/10 12:55 by Ryota Mibu
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: Creative Commons Attribution 4.0 International License
