Component Docs Guide
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 OSC, 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 (RST), are a good choice for documentation because:
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 OSC’, cross-referencing between component documentation was deemed critical. Sphinx and reStructuredText have built-in functionality that makes collating and cross-referencing component documentation easier.
The Sphinx version is defined in `documentation/etc/requirements.txt`
.
RST vs the Wiki - Which Docs 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.
Two examples on opposite ends of the spectrum:
Example 1: API documentation is often stored literally as code in the form of formatted comment sections. This would be an ideal choice for reStructuredText stored in a docs repo.
Example 2: Meeting notes, release plans – the wiki would be a better choice for this.
The Docs team encourages component teams to store as much documentation as reStructuredText as possible because:
The Docs team can more easily edit component documentation for grammar, spelling, clarity, and consistency
A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output
The documentation can easily be reorganized
Wiki articles tend to grow stale over time as the people who write them change positions or projects
RST Tools and Resources
For detailed information ReStructuredText and how to best use the format, see:
A list of RST tools is available on the Tools for Creating Documentation in RST page. Sphinx is also a good tool on Linux system.
In O-RAN SC, before you starting document your repo documentation, it is suggested to prepare a set of rst files (both required files and optional files) under your-repo/docs (e.g. doc/docs/).
Documentation team suggests to contain following files in your-repo/docs to help build up O-RAN SC documentation.
index.rst
the entrance of a repo documentation, includes what documentation files your repo has. You will need to list what optional files rst you have in your index.rst.overview.rst
state the overview of the your projectOptional files in the following are depends on what a specific repo needs. Your may need all of them or part of them.
installation-guides.rst
contains how to install O-RAN SC component
release-notes.rst
contains the release notes for the component
developer-guide.rst
contains information that a developer needs to know in order to work on the component
api-docs.rst
contains details on the component’s API. There are some good tools to help generate API document.
user-guide.rst
contains information on how to use and configure the component; most components will not have a user guideNote: It is not mandatory to have all files in your repository, please select the files you need.
Templates are available in the documentation project under doc/doc-templates. You can clone the documentation project or download from here. People who wish to contribute OSC docs please free free to download templates. Feedback are welcome.
Current list of templates:
The templates themselves also contain guidance on what topics to include in the contents. Please read the contents of the templates!
This section provides instructions for configuring your component's documentation area so the O-RAN-SC Jenkins will automatically build and deploy the material to https://o-ran-sc.readthedocs.io/en/latest/ upon change of any file within your docs/ directory. There are many options you can choose to configure your repo documentation in O-RAN SC.
A detailed guide for the setup process is here: Configure Repo for Documentation
Another option is git clone doc repo, in doc/doc-templates/ directory, your can have what your need. Please start with README.txt
The automated setup process that is documented at https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/jjb/lf-rtdv3-jobs.html
If you have questions about this process or need help, please contact the O-RAN-SC Documentation Project Technical Lead, weichen ni
If you have any questions on documentation, please send e-mail to Weichen Ni <niweichen@chinamobile.com>
Component Docs Guide
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 OSC, 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 (RST), are a good choice for documentation because:
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 OSC’, cross-referencing between component documentation was deemed critical. Sphinx and reStructuredText have built-in functionality that makes collating and cross-referencing component documentation easier.
The Sphinx version is defined in `documentation/etc/requirements.txt`
.
RST vs the Wiki - Which Docs 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.
Two examples on opposite ends of the spectrum:
Example 1: API documentation is often stored literally as code in the form of formatted comment sections. This would be an ideal choice for reStructuredText stored in a docs repo.
Example 2: Meeting notes, release plans – the wiki would be a better choice for this.
The Docs team encourages component teams to store as much documentation as reStructuredText as possible because:
The Docs team can more easily edit component documentation for grammar, spelling, clarity, and consistency
A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output
The documentation can easily be reorganized
Wiki articles tend to grow stale over time as the people who write them change positions or projects
RST Tools and Resources
For detailed information ReStructuredText and how to best use the format, see:
A list of RST tools is available on the Tools for Creating Documentation in RST page. Sphinx is also a good tool on Linux system.
In O-RAN SC, before you starting document your repo documentation, it is suggested to prepare a set of rst files (both required files and optional files) under your-repo/docs (e.g. doc/docs/).
Documentation team suggests to contain following files in your-repo/docs to help build up O-RAN SC documentation.
index.rst
the entrance of a repo documentation, includes what documentation files your repo has. You will need to list what optional files rst you have in your index.rst.overview.rst
state the overview of the your projectOptional files in the following are depends on what a specific repo needs. Your may need all of them or part of them.
installation-guides.rst
contains how to install O-RAN SC component
release-notes.rst
contains the release notes for the component
developer-guide.rst
contains information that a developer needs to know in order to work on the component
api-docs.rst
contains details on the component’s API. There are some good tools to help generate API document.
user-guide.rst
contains information on how to use and configure the component; most components will not have a user guideNote: It is not mandatory to have all files in your repository, please select the files you need.
Templates are available in the documentation project under doc/doc-templates. You can clone the documentation project or download from here. People who wish to contribute OSC docs please free free to download templates. Feedback are welcome.
Current list of templates:
The templates themselves also contain guidance on what topics to include in the contents. Please read the contents of the templates!
This section provides instructions for configuring your component's documentation area so the O-RAN-SC Jenkins will automatically build and deploy the material to https://o-ran-sc.readthedocs.io/en/latest/ upon change of any file within your docs/ directory. There are many options you can choose to configure your repo documentation in O-RAN SC.
A detailed guide for the setup process is here: Configure Repo for Documentation
Another option is git clone doc repo, in doc/doc-templates/ directory, your can have what your need. Please start with README.txt
The automated setup process that is documented at https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/jjb/lf-rtdv3-jobs.html
If you have questions about this process or need help, please contact the O-RAN-SC Documentation Project Technical Lead, weichen ni
If you have any questions on documentation, please send e-mail to Weichen Ni <niweichen@chinamobile.com>