documentation:configguide
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
documentation:configguide [2015/12/21 15:24] Christopher Price |
documentation:configguide [2016/02/08 14:58] (current) Ryota Mibu [Document structure] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== OPNFV Installation and Configuration guide ====== | + | ====== OPNFV Installation and Configuration guide documentation instruction ====== |
| ===== Document Purpose ===== | ===== Document Purpose ===== | ||
| Line 23: | Line 23: | ||
| The document is further compiled of project specific chapters, these include installation tool descriptions, feature configuration descriptions, and post installation validation procedures. Every project providing features into the platform that requires the configuration of specific components or features in the platform must provide a description in this document on how to enable the features. Please note: this covers only the configuration of the platform to enable the features or components, not the use of those features which is covered in the [[documentation:userguide|OPNFV user guide]]. | The document is further compiled of project specific chapters, these include installation tool descriptions, feature configuration descriptions, and post installation validation procedures. Every project providing features into the platform that requires the configuration of specific components or features in the platform must provide a description in this document on how to enable the features. Please note: this covers only the configuration of the platform to enable the features or components, not the use of those features which is covered in the [[documentation:userguide|OPNFV user guide]]. | ||
| - | All project specific files to be compiled into the Installation and Configuration guide must be stored in your projects configguide folder. | + | All project specific files to be compiled into the Installation and Configuration guide must be stored in your projects configguide folder, templates for these files can be found in the opnfvdocs repo. |
| - | | Installation and Configuration guide directory: |''<repo>/docs/configguide/''| | + | | Installation and Configuration guide directory: |''<repo>/docs/configguide/''| | |
| - | | Installer configuration guide: |''<repo>/docs/configguide/installerconfig.rst''| | + | | Installer configuration guide: |''<repo>/docs/configguide/installerconfig.rst''|[[https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=docs/configguide/installerconfig.rst;hb=HEAD|template]]| |
| - | | Feature configuration guide: |''<repo>/docs/configguide/featureconfig.rst''| | + | | Feature configuration guide: |''<repo>/docs/configguide/featureconfig.rst''|[[https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=docs/configguide/featureconfig.rst;hb=HEAD|template]]| |
| - | | Post installation procedures: |''<repo>/docs/configguide/postinstall.rst''| | + | | Post installation procedures: |''<repo>/docs/configguide/postinstall.rst''|[[https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=docs/configguide/postinstall.rst;hb=HEAD|template]]| |
| ==== Including your Documentation ==== | ==== Including your Documentation ==== | ||
| Line 34: | Line 34: | ||
| 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 the opnfvdocs repository, you should copy the relevant templates to the /docs/configguide directory in your repository. For instance if I wanted to document enabling my feature set in the platform I would follow an example like: | 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 the opnfvdocs repository, you should copy the relevant templates to the /docs/configguide directory in your repository. For instance if I wanted to document enabling my feature set in the platform I would follow an example like: | ||
| - | ' mkdir <my_repo>/docs/configguide ' | ||
| - | ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git ' | ||
| - | ' cp opnfvdocs/docs/configguide/featureconfig.rst <my_repo>/docs/configguide ' | ||
| - | ' cp opnfvdocs/docs/configguide/postinstall.rst <my_repo>/docs/configguide ' | ||
| - | You should then add the relevant information to the template that will explain the configuration of your feature and instructions for validating that the feature was enabled successfully //like checking the results of specific test cases//. | + | ' mkdir <my_repo>/docs/configguide ' |
| + | ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git ' | ||
| + | ' cp opnfvdocs/docs/configguide/featureconfig.rst <my_repo>/docs/configguide ' | ||
| + | ' cp opnfvdocs/docs/configguide/postinstall.rst <my_repo>/docs/configguide ' | ||
| - | Once your installer or feature documentation is ready you should ensure they are compiled into the master file by adding them to the master index.rst file in the opnfvdocs repository. The index.rst fils is structured in such a way that you should refer to your document in the correct section of the index.rst document structure. The relevant sections for compiling project specific information are: | ||
| - | * Installation Description - //for adding installation tool configuration information// | + | You should then add the relevant information to the template that will explain the configuration of your feature and instructions for validating that the feature was enabled successfully //like checking the results of specific test cases//. Be sure to maintain the creative commons license from the template and ensure all your documentation files include the license information. |
| - | * Feature Description - //for adding feature specific configuration information// | + | |
| - | * Post Configuration Activities - //describing how to validate the configuration was performed successfully// | + | |
| - | An example of how to add your documentation to the relevant sections of the index.rst file might be: | + | Once your installer or feature documentation is ready you should ensure they are compiled into the master file by adding them to the master files in the opnfvdocs repository. The index.rst file is structured in such a way that it will pull composite material via a staging file, staging files are identifiable by the "-" in their file names. Examples of the staging files are feature-config.rst, installer-config.rst and post-install.rst. You should add references to your input documents in the correct locations in these staging files. The relevant staging files for compiling project specific information are: |
| + | | Installer install and configuration documentation: |''opnfvdocs/docs/configguide/installer-config.rst''| | ||
| + | | Feature specific configuration documentation: |''opnfvdocs/docs/configguide/feature-config.rst''| | ||
| + | | Post installation procedures: |''opnfvdocs/docs/configguide/post-install.rst''| | ||
| - | ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git ' | + | An example of how to add your documentation to the relevant sections of the post-install.rst file might be: |
| + | ' git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git ' | ||
| + | ' cd opnfvdocs ' | ||
| + | ' git review -s ' | ||
| + | ' vim docs/configguide/post-install.rst ' | ||
| - | ' cd opnfvdocs ' | + | At this point you should add the references to your files into the post-install.rst file, these should be added in alphabetical order based on the projects repository name. For instance in the post installation procedures staging file you would add an include line for your project as shown below: |
| + | The following sections provide information on how to validate the features you have | ||
| + | installed in your scenario: | ||
| + | .. include:: ../projects/copper/configguide/postinstall.rst | ||
| + | .. include:: ../projects/<my_repo>/configguide/postinstall.rst | ||
| - | ' git review -s ' | + | If this is the first contribution from your project to the composite document files you will need to add your project to the //build-composite.sh// file in the opnfvdocs directory. This is done my editing the jsdgf file and adding your repository name to the //get_repo_names()// function of the script. Assuming you are still in the opnfvdocs directory edit the file with the following command: |
| + | ' vim build-composite.sh ' | ||
| - | ' vim docs/configguide/index.rst ' | + | Once you have the file open, add your projects repository to the //get_repo_names()// function: |
| - | At this point you should add the references to your files into the index.rst file, for instance in the feature description section you would add ''../../<my_repo>/docs/configguide/featureconfig.rst'' and in the Post Configuration Activities section you would add ''../../<my_repo>/docs/configguide/postinstall.rst''. | + | get_repo_names() { |
| + | # NOTE: Not all repositories are ready for the composite docs, | ||
| + | # so we have the repo name list here to add project docs | ||
| + | # one by one. This will be replaced by the list in project.cfg . | ||
| + | # grep -v '^#' releng/jjb/opnfvdocs/project.cfg | sort | ||
| + | echo "sdnvpn" | ||
| + | echo "<my_repo>" | ||
| + | Once you have made these changes you need to push the patch back to the opnfvdocs team for review and integration. | ||
| - | ' git add . ' | + | ' git add . ' |
| - | + | ' git commit --signoff --all ' | |
| - | + | ' git review ' | |
| - | ' git commit --signoff --all ' | + | |
| - | + | ||
| - | + | ||
| - | ' git review ' | + | |
documentation/configguide.1450711494.txt.gz · Last modified: 2015/12/21 15:24 by Christopher Price
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: Creative Commons Attribution 4.0 International License
