API references cleanup

[mmahsereci]

The API references have several issues that should be addressed. These are, among others:

• Some latex formulas are not rendered correctly

• For some classes, the parameter descriptions are not rendered at all as the docstring is split. The parameter descriptions need to be moved to the right place. Example:

  This will not render the description of my_param:

  class MyCass:
      """This is my class."""
  
      def __init__(self, my_parameter):
          """
          :param my_parameter: Description of parameter.
          """
  

  This will :

  class MyCass:
      """This is my class.
  
    :param my_parameter: Description of parameter.
    """
  
      def __init__(self, my_parameter):
        ...
  

• :raises: ExcetionType are partially not documented.

• .. note:: and .. seealso:: is not used even though a note is present in the docstring.

• Sentences are incomplete, e.g., dots . are missing, or they start without a capital letter.

• There are inconsistencies in naming. For example sometimes the number of points are called num_points and sometimes n_points, or the number of input dimensions are sometimes called num_dim and sometimes input_dim. This is confusing to users.

• Some docstrings do not exist or are incomplete

• ...

Another thing that might be worth thinking about is to clean up the import structure and pulling some imports one level up (this may minorly break some code as imports change). For example instead of from emukit.quadrature.loop.specific_loop import SpecificLoop we should only have from emukit.quadrature.loop import SpecificLoop. It's more user friendly and the docs are cleaner.

We should probably go through the modules one by one and see if the issues are resolved.

---

Modules docs that have been corrected

• bayesian optimization
• benchmarking
• core
• examples
• experimental design
• model wrappers
  • quadrature wrappers GPy quadrature wrapper docs #413
  • ...
• multi fidelity
• quadrature Fixing docstrings and imports in quadrature #412
• samplers
• sensitivity
• test functions
  • quadrature test functions Fixing docstrings and imports in quadrature #412
  • ...

[sheikheddy]

https://nbviewer.jupyter.org/github/amzn/emukit/blob/master/notebooks/Emukit-tutorial-Bayesian-quadrature-introduction.ipynb

I couldn't find anything. Could you point out some examples? Otherwise we might want to close this issue

Edit: nvm, found it https://emukit.readthedocs.io/en/latest/api/emukit.quadrature.acquisitions.html

I might put some time into listing what exactly seems broken and then see if I can modify https://github.com/amzn/emukit/tree/master/emukit/quadrature locally and run sphinx to fix the latex in the docs.

[mmahsereci]

Thank you @sheikheddy, much appreciated!

[mmahsereci]

This is fixed now for quadrature package via #413 #412 but not for other packages.

[apaleyes]

@mmahsereci can you mention those other packages here, so the scope of the issue is clear?