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:
- They are editor agnostic
- The source is nearly as easy to read as the rendered text
- Documentation can be treated exactly as source code is treated
- Shallow learning curve
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.
Start your repo documentation
Documentation directory Structure
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/).
Configure Doc Builds
A detailed guide for the setup process is here: Configure Repo for Documentation
Required Files
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 file you have in your index.rst.overview.rst
state the overview of the your project
Optional Files
Optional 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 componentrelease-notes.rst
contains the release notes for the componentdeveloper-guide.rst
contains information that a developer needs to know in order to work on the component- this should be very technical, aimed at people who want to help develop the components
- this should be how the component does what it does, not a requirements document of what the component should do
- this should contain what language(s) and frameworks are used, with versions
- this should contain how to obtain the code, where to look at work items (Jira tickets), how to get started developing
api-docs.rst
contains details on the component’s APIuser-guide.rst
contains information on how to use and configure the component; most components will not have a user guide- if the guide contains sections on third-party tools, is it clearly stated why the OSC platform is using those tools? are there instructions on how to install and configure each tool/toolset?
- does the guide state who the target users are? for example, modeler/data scientist, OSC platform admin, marketplace user, design studio end user, etc
- if there are instructions, they are clear, correct, and fit for purpose
- does the guide contain information more suited for a different guide?
- a user guide should be how to use the component or system; it should not be a requirements document
- a user guide should contain configuration, administration, management, using, and troubleshooting sections for the feature
Note: It is not mandatory to have all files in your repository, please select the files you need.
Templates
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(found bugs, fixing...):
The templates themselves also contain guidance on what topics to include in the contents. Please read the contents of the templates!
Configure Repo for Documentation
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.
If you have questions about this process or need help, please contact the O-RAN-SC Documentation Project Technical Lead, weichen ni
Option 1: please git clone doc repo, in doc/doc-templates/ directory, your can have what your need. Please start with README.txt
Option 2: Please use the automated setup process that is documented at https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/jjb/lf-rtdv3-jobs.html
Option 3: If that process fails or you need to trouble-shoot problems, this page gives step by step details.
Step 1: Add files to your-repo root
1.1 Create or extend file .gitignore in the root of your repository with the following content:
# documentation .tox docs/_build/
1.2 Create file .readthedocs
Create a file in the root of your repository called .readthedocs.yaml (yes there's a leading dot) with the following content:
--- version: 2 formats: - htmlzip build: image: latest python: version: 3.7 install: - requirements: docs/requirements-docs.txt sphinx: configuration: docs/conf.py
1.2 Create file tox.ini
Create or extend a file in the root of your repostory called tox.ini with the following content:
# documentation only [tox] minversion = 2.0 envlist = docs, docs-linkcheck, skipsdist = true [testenv:docs] basepython = python3 deps = sphinx sphinx-rtd-theme sphinxcontrib-httpdomain recommonmark lfdocs-conf commands = sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html echo "Generated docs available in {toxinidir}/docs/_build/html" whitelist_externals = echo [testenv:docs-linkcheck] basepython = python3 deps = sphinx sphinx-rtd-theme sphinxcontrib-httpdomain recommonmark lfdocs-conf commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
Step 2: Add files to your-repo/docs
In these steps you will create files in the "docs" subfolder of your repository. Please note that "docs" is a magic string, the directory name must be exactly that. Please use templates from the DOC area to create basic documentation files like "index.rst" and so on.
2.1 Make an empty directory "_static"
cd docs mkdir _static
2.2 Create an image file logo.png in the new _static/ directory. Here's a good source for the image:
2.3 Now go back to the docs/ directory and create file conf.py with exactly the following content:
from docs_conf.conf import * linkcheck_ignore = [ 'http://localhost.*', 'http://127.0.0.1.*', 'https://gerrit.o-ran-sc.org.*' ]
2.4 Create file conf.yaml with the following content, but be sure to use your project name, not "your-repo":
--- project_cfg: oran project: your-repo
2.5 Create an image file favicon.ico in the docs/ directory. Here's a good source for the icon:
2.6 Create file requirements-docs.txt with exactly the following content:
sphinx sphinx-rtd-theme sphinxcontrib-httpdomain recommonmark lfdocs-conf
Step 3: Test locally
Working in the root of the repository, issue the following command to generate documentation. This assumes you have Python and Tox installed on the machine where you are working. Note a common error message (see below) comes from RST formatting warning (warnings treated as errors). Fix the underlying RST (in the example that's installation-guides.rst) and try again.
tox -e docs,docs-linkcheck ### Possible/typical error message in the output // fix by fixing the underlying RST document Warning, treated as error: /home/fedora/tmp/doci/aaa/docs/index.rst:23:toctree contains reference to document 'installation-guides' that doesn't have a title: no link will be generated ERROR: InvocationError for command '/home/fedora/tmp/doci/aaa/.tox/docs-linkcheck/bin/sphinx-build -W -b linkcheck -d /home/...(exited with code 2)
Step 4: Add a link to your-repo documentation
4.1 Clone the doc area:
git clone "https://gerrit.o-ran-sc.org/r/doc"
4.2 Add a mapping from key to URL in the conf.py file, for example:
intersphinx_mapping['your-repo'] = ('https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-your-repo/en/%s' % branch, None a
4.3 Add a link to your mapping key in an appropriate file such as index.rst, for example:
* :doc:`Your Project <your-repo:index>
Step 5: Test publication
Edit a file in your docs/ area, commit the file to git and push your commit to Gerrit for review. You should see a documentation build job start.
Writing Guidelines
Following these writing guidelines will keep OSC documentation consistent and readable. Only a few areas are covered below, as we don’t want to make it too complex. You can’t go wrong keeping things simple and clear.
Don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to this guide than no information at all. OSC’ Documentation project team will be happy to help you with the prose.
General Guidelines for All Documents
- Use standard American English and spelling
- Use consistent terminology
- Write in the active voice, using present simple tense when possible
- Write objective, professional content
- Keep sentences and paragraphs short and clear
- Use a spell checker
Abbreviations and Acronyms
Write out the term the first time it appears in the document, immediately followed by the acronym or abbreviation in parentheses, i.e. ReStructuredText (RST). Then use the acronym in the rest of the document. In diagrams, if space allows, write out the full term. Use “an” before an acronym that begins with a vowel sound when spoken aloud; use “a” before an acronym that begins with a consonant sound when spoken aloud. Examples: an RST file, a PMML file.
GUI Elements
In general, write menu names as they appear in the UI. For example, if a menu or item name is all caps, then write it all caps in the document.
Headings (Titles)
- Use brief, but specific, informative titles
- Use capitalization; do not end with a period or colon
- Use a gerund to begin section titles if it makes sense. Examples: Configuring, Managing, Starting
- Use descriptive titles for tables and figures titles; do not number tables or figures; do not (in general) add titles for screen shots
Use the following to create the Document title:
= with overline/underline
Use the following symbols to create headings:
Section 1: * with overline/underline
Section 1.1: - with underline
Section 1.1.1: + with underline
Section 1.1.1.1: ^ with underline
Consider rewriting the content if your document needs more than 4 levels of headings.
Non-Numbered Headings in RST
Below is an example of how to denote headings of various levels in RST.
See the Section Headers Example - No Automatic Numbering for how this renders in HTML.
================= H1 Document Title ================= *************** Section 1 Title *************** Section 1.1 Title ----------------- Section 1.1.1 Title +++++++++++++++++++ Section 1.1.1.1 Title ^^^^^^^^^^^^^^^^^^^^^ Section 1.1.1.1 Title2 ^^^^^^^^^^^^^^^^^^^^^^ Another Section at the 1.1.1 Level ++++++++++++++++++++++++++++++++++ How the Header is Underlined Makes all the Difference +++++++++++++++++++++++++++++++++++++++++++++++++++++ Section 1.2 Title ----------------- Section 1.2.1 Title +++++++++++++++++++ Section 1.2.2 Title +++++++++++++++++++ *************** Section 2 Title *************** *************** Section 3 Title ***************
Automatically Numbered Headings in RST
RST supports automatic numbering of sections. Place the sectnum directive at the top of your page. See the 1 Section Headers Example - Automatic Numbering for how this renders in HTML. Note that RST considers the Document Title to be the first Header and will number it!
================= H1 Document Title ================= .. sectnum:: *************** Section 1 Title *************** Section 1.1 Title ----------------- Section 1.1.1 Title +++++++++++++++++++ Section 1.1.1.1 Title ^^^^^^^^^^^^^^^^^^^^^ Section 1.1.1.1 Title2 ^^^^^^^^^^^^^^^^^^^^^^ Another Section at the 1.1.1 Level ++++++++++++++++++++++++++++++++++ How the Header is Underlined Makes all the Difference +++++++++++++++++++++++++++++++++++++++++++++++++++++ Section 1.2 Title ----------------- Section 1.2.1 Title +++++++++++++++++++ Section 1.2.2 Title +++++++++++++++++++ *************** Section 2 Title *************** *************** Section 3 Title ***************
If your guide has enough content, consider breaking it up into chapters, with one chapter per RST file.
Having Questions
If you have any questions on documentation, please send e-mail to Weichen Ni <niweichen@chinamobile.com>