[API Doc] Syntax-related issues and other possible problems in Nano API doc

[AndyLuo1029]

This issue summarized most problems in Nano API modules (different sections in API doc page) , please go through it and revise your responsible module according to the problems it has.

Classification and explaination of problems

General Problems

For some general problems, the modules are classified and listed according to the problems they have.

TIPS:Most of the general suggestions are from #6421 , authored by @Oscilloscope98 . You can check this issue for more information about general suggestions in detail.

1. Wrong rst inline-code syntax.

For parameter's value options written in "value" or 'value' , it would be clearer to write them through rst inline code syntax as ``value`` to ensure that it will be displayed in correct inline code format in the doc.

Incorrect syntax examples:

If the module you are responsible for is tagged with this problem, please check if there is any inline-code problem in the class description/ method description/ variable description of the module.

2. Wrong rst param syntax.

Incorrect param rst syntax can cause errors in the generation and display of API documentation.

Incorrect display examples:

Correct display example:

If the module you are responsible for is tagged with this problem, please check if there is any param syntax problem in the variable description of the module.

3. Problems related to the return field of the method.

The return value format is not consistent in the method explanation of parts of the API documentation. Problems include:

• Some methods don't give the return value

• Some methods describe the return value in methods description instead of writing it through the return field

• Some methods don't write the return value in correct syntax, resulting in display problems

  Such inconsistency is not user-friendly. It is suggested that all methods can be unified to add the return value field in correct syntax, and explain the return value clearly (None for methods with no return value ).

  If the module you are responsible for is tagged with this problem, please check return fields of all the methods it contains.

4. Raw hyperlinks.

When link to reference page, please add hyperlink in correct syntax to get appropriate display.

Incorrect hyperlink add example：

If the module you are responsible for is tagged with this problem, please check all hyperlinks in it.

5. Incorrectly-displayed quote block.

Some API explanations are incorrectly displayed in quote blocks. This problem is always related to incorrect syntax for lists. Such erroneous displays should be corrected.

Incorrectly-displayed quote block example:

If the module you are responsible for is tagged with this problem, please check where the quote block is miss-used.

Special Problems

A few modules have specific issues and are listed after the general problems classification. Please check if there are special problems with the module you are responsible for.

Classification of general problems

This section classified Nano API modules (different sections in API doc page) based on the type of problems they contain, please go through all the types of problems to checkout whether your responsible module has some of the problems.

1. Wrong rst inline-code syntax

Nano PyTorch API

• bigdl.nano.pytorch.Trainer
• bigdl.nano.pytorch.InferenceOptimizer
• bigdl.nano.pytorch.TorchNano
• Patch API

Nano Tensorflow API

• bigdl.nano.tf.keras
• bigdl.nano.tf.optimizers

Nano HPO API

• Search Space
• HPO for Tensorflow
• HPO for PyTorch

2. Wrong rst param syntax

Nano PyTorch API

• bigdl.nano.pytorch.InferenceOptimizer (Method optimize, param validation_data)

Nano Tensorflow API

• bigdl.nano.tf.keras (Method fit's description about additional param num\_processes)

Nano HPO API

• Search Space (class bigdl.nano.automl.hpo.space.Categorical params)

3. Problems related to the return field of the method

Nano PyTorch API

• bigdl.nano.pytorch.Trainer
• bigdl.nano.pytorch.InferenceOptimizer
• Patch API

Nano Tensorflow API

• bigdl.nano.tf.keras

Nano HPO API

• HPO for Tensorflow

4. Raw hyperlinks

Nano PyTorch API

• bigdl.nano.pytorch.Trainer
• bigdl.nano.pytorch.InferenceOptimizer

Nano Tensorflow API

• bigdl.nano.tf.keras

5. Incorrectly-displayed quote blocks

Nano HPO API

• HPO for Tensorflow

Special problems

This section listed all the modules that have some special problems, please go through it to checkout whether your responsible module are here.

Nano PyTorch API -> bigdl.nano.pytorch.Trainer:

• class bigdl.nano.pytorch.Trainer :

  • Class parameters and parameters description do not match. The class have parameters \*args: Any, \*\*kwargs: Any but in description there are more parameters with specific explanation.

• method compile :

  • Parameter scheduler doesn't have detailed description.

• method quantize :

  • Parameter use_ipex doesn't have detailed description.

• method save_checkpoint :

  • All parameters don't have detailed description.

Nano PyTorch API -> bigdl.nano.pytorch.InferenceOptimizer:

• method quantize :

  • Parameter use_ipex doesn't have detailed description.

Nano PyTorch API -> bigdl.nano.pytorch.TorchNano:

• class bigdl.nano.pytorch.TorchNano :

  • Class parameters and parameters description do not match. The class have parameters \*args: Any, \*\*kwargs: Any but in description there are more parameters with specific explanation.

Nano Tensorflow API -> bigdl.nano.tf.keras:

• method trace :

  • The order of explanation of param accelerator and input_sample are reversed. The explanation of param accelerator should before input_sample.

Nano HPO API -> Search Space:

• class bigdl.nano.automl.hpo.space.Bool

  • Params default=None, prefix=None don't have detailed explanation.

Nano HPO API -> HPO for PyTorch:

• class bigdl.nano.pytorch.Trainer :

  • Class parameters and parameters description do not match. The class have parameters \*args: Any, \*\*kwargs: Any but in description there are more parameters with specific explanation.