OpenVINO documentation is built using Sphinx and the reStructuredText formatting. That means the basic formatting rules need to be used:
OpenVINO documentation is developed to be easily readable in both html and reStructuredText. Here are some suggestions on how to make it render nicely and improve document clarity.
They are made by "underscoring" text with punctuation marks (at least as many marks as letters in the underscored header). We use the following convention:
H1
====================
H2
####################
H3
++++++++++++++++++++
H4
--------------------
H5
....................
In programming, a limit of 80 characters per line is a common BKM. It may also apply to reading natural languages fairly well. For this reason, we aim at lines of around 70 to 100 characters long. The limit is not a strict rule but rather a guideline to follow in most cases. The breaks will not translate to html, and rightly so, but will make reading and editing documents in GitHub or an editor much easier.
Tables may be difficult to implement well in websites. For example, longer portions of text, like descriptions, may render them difficult to read (e.g. improper cell widths or heights). Complex tables may also be difficult to read in source files. To prevent that, check the table directive documentation and see our custom directives. Use the following guidelines for easier editing:
- For very big and complex data sets: use a list instead of a table or remove the problematic content from the table and implement it differently.
- For very big and complex data sets that need to use tables: use an external file (e.g. PDF) and link to it.
- For medium tables that look bad in source (e.g. due to long lines of text), use the reStructuredText list table format.
- For medium and small tables, use the reStructuredText grid or simple table formats.
There are several directives Sphinx uses for linking, each has its purpose and format. Follow these guidelines for consistent results:
- Avoid absolute references to internal documents as much as possible (link to source, not html).
- Note that sphinx uses the "back-tick" character and not the "inverted-comma" => ` vs. '
- When a file path starts at the same directory is used, put "./" at its beginning.
- Always add a space before the opening angle bracket ("<") for target files.
Use the following formatting for different links:
-
link to an external page / file
`text <url> `__- use a double underscore for consistency
-
link to an internal documentation page / file
:doc:`a docs page <relative file path>`- Link to an rst or md file within our documentation, so that it renders properly in html
-
link to a header on the same page
'a header in the same article <this-is-section-header-title>`__- anchors are created automatically for all existing headers
- such anchor looks like the header, with minor adjustments:
- all letters are lower case,
- remove all special glyphs, like brackets,
- replace spaces with hyphens
-
Create an anchor in an article
.. _anchor-in-the target-article::- put it before the header to which you want to link
- See the rules for naming anchors / labels at the bottom of this article
-
link to an anchor on a different page in our documentation
:ref:`the created anchor <anchor-in-the target-article>`- link to the anchor using just its name
-
anchors / labels
Read about anchors
Sphinx uses labels to create html anchors, which can be linked to from anywhere in documentation. Although they may be put at the top of any article to make linking to it very easy, we do not use this approach. Every label definition starts with an underscore, the underscore is not used in links.
Most importantly, every label needs to be globally unique. It means that it is always a good practice to start their labels with a clear identifier of the article they reside in.