Documentation Guide

Here list several writing tips and guidelines you could refer to if you want to add/modify documents for BigDL documentation. The source code of our documentation is available here.

Tip

You could refer here if you would like to test your local changes to BigDL documentation.

1. How to add a new document

1.1 Decide whether to add a reStructuredText (.rst) file or a CommonMark (.md) file

In our documentation, both reStructuredText (.rst) and CommonMark (.md) files are allowed to use. In convension, we use .rst file in index pages, and .md files for other pages.

Here shows an overview of our documentation structure tree:

Index pages (nodes filled with blue) are the ones supposed to lead to further pages. In the structure above, they are nodes with descendants.

Note

In convension, we use .rst file for index pages becuase various web components (such as cards, note boxes, tabs, etc.) are more straightforward to be inserted in our documentation through reStructuredText. And it is a common case in our documentation that index pages include various web components.

1.2 Add the new document to the table of contents (ToC)

For clear navigation purposes, it is recommended to put the document in the ToC. To do this, you need to insert the relative path to the newly-added file into the _toc.yml file, according to its position in the structure tree.

Tip

When adding a new document, you should always check whether to put relative link directing to it inside its parent index page, or inside any other related pages.

Warning

According to sphinx-external-toc document, “each document file can only occur once in the ToC”.

For API related documents, we still use in-file .. toctree:: directives instead of putting them inside _toc.yml. You could refer here for example usages.

2. Differentiate the syntax of reStructuredText and CommonMark

As mentioned above, our documentation includes both .rst and .md files. They have different syntax, please make sure you do not mix the usage of them.

See also

You could refer here for reStructuredText syntax examples, and here for CommonMark specifications.

Here list several use cases where syntax in .rst and .md are often confused:

	reStructuredText	CommonMark
Inline code	``inline code``	`inline code`
Hyperlinks	`Relative link text <relatve/path/to/the/file>`_ `Absolute link text <https://www.example.com/>`_	[Relative link text](relatve/path/to/the/file) [Absolute link text](https://www.example.com/)
Italic	`italicized text` *italicized text*	*italicized text*
Italic & bold	Not supported, needed help with css	***italicized & bold text***

Note

When linking to a .rst file in a .md file, replace the .rst with .html in the relative path to avoid errors. That is, if you want to link to the example.rst in a .md file, use

[Example](relatve/path/to/example.html)

2.1 Tips when adding docstrings in source code for API documentation

According to the sphinx.ext.autodoc document, docstrings should be written in reStructuredText. We need to make sure that we are using reStructuredText syntax in the source code docstrings for API documentation.

There are two field lists syntax often used in API documentation for parameter definition and return values. Let us take a snippet from bigdl.nano.pytorch.InferenceOptimizer.get_best_model as an example:

:param use_ipex: (optional) if not None, then will only find the
       model with this specific ipex setting.
:param accuracy_criterion: (optional) a float represents tolerable
       accuracy drop percentage, defaults to None meaning no accuracy control.
:return: best model, corresponding acceleration option

Important

The following lines of one parameter/return definition should be indented to be rendered correctly.

Tip

Please always check whether corresponding API documentation is correctly rendered when changes made to the docstrings.

3. Common components in .rst files

Headers	Header Level 1 ========================= Header Level 2 ------------------------- Header Level 3 ~~~~~~~~~~~~~~~~~~~~~~~~~ Header Level 4 ^^^^^^^^^^^^^^^^^^^^^^^^^	Note that the underline symbols should be at least as long as the header texts. Also, we do not expect maually-added styles to headers. You could refer here for more information on reStructuredText sections.
Lists	* A unordered list * The second item of the unordered list with two lines #. A numbered list 1. A nested numbered list 2. The second nested numbered list #. The second item of the numbered list	Note that the number of spaces indented depends on the markup. That is, if we use ‘* ‘/’#. ‘/’10. ‘ for the list, the following contents belong to the list or the nested lists after it should be indented by 2/3/4 spaces. Also note that blanks lines are needed around the nested list. You could refer here for more information on reStructuredText lists.
Note, Warning, Danger, Tip, Important, See Also boxes	.. note:: This is a note box. .. warning:: This is a warning box. .. danger:: This is a danger box. .. tip:: This is a tip box. .. important:: This is an important box. .. seealso:: This is a see also box.	Note This is a note box. Warning This is a warning box. Danger This is a danger box. Tip This is a tip box. Important This is an important box. See also This is a see also box.
Code blocks	.. code-block:: [language] some code in this language .. code-block:: python some python code	All the supported language argument for syntax highlighting can be found here.
Tabs	.. tabs:: .. tab:: Title 1 Contents for tab 1 .. tab:: Title 2 Contents for tab 2 .. code-block:: python some python code	Title 1Title 2 Contents for tab 1 You could refer here for more information on the usage of tabs.
Cards in grids	.. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: **Header** ^^^ A normal card. +++ :bdg-link:`Footer <relatve/path>` .. grid-item-card:: :link: https://www.example.com/ :class-card: bigdl-link-card **Header** ^^^ A link card. +++ Footer	Header A normal card. Footer Header A link card. Footer You could refer here for more information on the usage of cards, and here for cards in grids. Note that 1 2 2 2 defines the number of cards per row in different screen sizes (from extra-small to large).
Mermaid digrams	.. mermaid:: flowchart LR A(Node A) B([Node B]) A -- points to --> B A --> C{{Node C}} classDef blue color:#0171c3; class B,C blue;	flowchart LR A(Node A) B([Node B]) A -- points to --> B A --> C{{Node C}} classDef blue color:#0171c3; class B,C blue; Mermaid is a charting tool for dynamically creating/modifying diagrams. Refer here for more Mermaid syntax.

3.1 Use reStructuredText in .md files

You could embed reStructuredText into .md files through putting reStructuredText code into eval_rst code block. It is really useful when you want to use components such as sepcial boxes, tabs, cards, Mermaid diagrams, etc. in your .md file.

```eval_rst
any contents in reStructuredText syntax
```

```eval_rst
.. note::
   
   This is a note box.

.. mermaid::
   
   flowchart LR
      A --> B
```

Important

Any contents inside eval_rst code block should follow the reStructuredText syntax.

4. Common components in .md files

Headers	# Header Level 1 ## Header Level 2 ### Header Level 3 #### Header Level 4	Note that we do not expect maually-added styles to headers.
Lists	- A unordered list - The second item of the unordered list with two lines 1. A numbered list * A nested unordered list * The second nested unordered list 2. The second item of the numbered list	Note that the number of spaces indented depends on the markup. That is, if we use ‘- ‘/’1. ‘/’10. ‘ for the list, the following contents belong to the list or the nested lists after it should be indented by 2/3/4 spaces.
Code blocks	```[language] some code in this language ``` ```python some python code ```	All the supported language argument for syntax highlighting can be found here.

5. How to include Jupyter notebooks directly inside our documentation

If you want to include a Jupyter notebook into our documentation as an example, a tutorial, a how-to guide, etc., you could just put it anywhere inside BigDL/docs/readthedocs/source dictionary, and link it into _toc.yml file.

However, if you want to render a Jupyter notebook located out of BigDL/docs/readthedocs/source dictionary into our documentation, the case is a little bit complicated. To do this, you need to add a file with .nblink extension into BigDL/docs/readthedocs/source , and link the .nblink file into _toc.yml.

The .nblink file should have the following structure:

{
    "path": "relative/path/to/the/notebook/you/want/to/include"
}

See also

You could find here for an example of .nblink usage inside our documentation.

5.1 How to hide a cell from rendering

If you want to hide a notebook markdown/code cell from rendering into our documentation, you could simply add "nbsphinx": "hidden" into the cell’s metadata.

Here shows an examlpe of a markdown cell hidden from rendering:

{
"cell_type": "markdown",
"metadata": {
   "nbsphinx": "hidden"
},
"source": [
   ...
]
}

Tip

You could simply open the notebook through text editor to edit the metadata of each cell.

Note

Currently we could not hide the output/input code cell individually from rendering as they have the same metadata.

5.2 Note/Warning/Related Readings boxes

In convension, in the markdown cell of notebooks, we create note/warning/related reading boxes with the help of quote blocks and emoji:

> 📝 **Note**
>
> This is a note box in notebooks.

> ⚠️ **Warning**
> 
> This is a warning box in notebooks.

> 📚 **Related Readings**
> 
> This is a related readings box in notebooks.