Complete Example#

In this page we will provide the basic structure for a docstring for any VerticaPy function that we need to follow to create professional and uniform documentation. We will show an example docstring for a couple of functions and highlight some diverse aspects of the rst syntax. At the end of the page, there are instructions to test out/check out your documentation page based on a test file.

Structure for docstring#

An ideal docstring should have the following struvture:

Version information#

On the top of every function’s documentation we can write whether a function is new using:

.. versionadded:: X

New in version X.

Or we can also mention if the function was deprecate using:

.. deprecated:: Y.0

Deprecated since version Y.0.

Or if the version changed:

.. versionchanged:: Z.0.0

Changed in version Z.0.0.

Note

This may not be applicable to all the functions because of most of the functions are already part of VerticaPy.

Hint

For a list of all admonitions, check out: https://sphinx-themes.org/sample-sites/furo/kitchen-sink/admonitions/

Description of the function#

We can write a few lines describing the functionality. This is mandatory.

We should elaborate the function as much ass possible. Best practice would be to write one summary line at the top. And then add details.

Do not forget to use “ ` ` “ (without space in between) to show VerticaPy objects. This creates a special inline block. Look at the example below:

def one_hot_encode(
        self,
        prefix: Optional[str] = None,
        prefix_sep: str = "_",
        drop_first: bool = True,
        use_numbers_as_suffix: bool = False,
    ) -> "vDataFrame":
    """
    Encodes the :py:class:`~vDataColumn` with  the One-Hot Encoding algorithm.

    One hot encoding will be done on the select column. The result will be outputted in new columns thus resulting in additional columns added to the table.
    The first category/dummy will be dropped by default unless stated otherwise by the parameter ``drop_first``.
    """

Output:

Encodes the vDataColumn with the One-Hot Encoding algorithm.

One hot encoding will be done on the select column. The result will be outputted in new columns thus resulting in additional columns added to the table. The first category/dummy will be dropped by default unless stated otherwise by the parameter drop_first.

Parameters#

Next, we need to add the details of the parameters in the Parameters heading. We can do this by writing “——-” underneath the Parameters heading.

For each parameter, we should also add the type of input along with the line explaining the parameter.

For example

"""
Parameters
-----------
x: integer
    x is the input
"""

Output:

x: integer
x is the input

Returns#

We simple write what the function returns using the Returns heading:

"""
Returns
-------
obj
    Plotting Object.
"""

Output:

obj
Plotting Object.

Examples#

In the examples, we can provide the code syntax to run the function. But first we need to create the Examples heading in a similar way:

Examples
--------

Below the heading, we have multiple ways to show our result. The simplest way is to just make code block and type in input and output. Autoamtically, python syntax will be highlighted using the code below:

.. code-block:: python

>>> x = [1,2,3]
>>> max(x)
3

Output:

x = [1,2,3]
max(x)
3

We can also run the code that is displayed:

.. ipython:: python

    x = 2
    y = 3
    x + y

Output:

x = 2

y = 3

x + y
Out[3]: 5

The above code will display and execute the python code as well. This can be useful where you don’t want to hardcode the results.

Example - Figures / Equations#

Figures and equations should be added with examples to effectively describe our functions.

To add equations, use the .. math:: directive:

.. math::

(a + b)^2 = a^2 + 2ab + b^2

Output:

\[\]

(a + b)^2 = a^2 + 2ab + b^2

To add figures, you can any use either VerticaPy directly, or matplotlib. In VerticaPy, we have three plotting libraries that can switching using the following syntax: verticapy.set_options("plotting_lib":"matplotlib").

Matplotlib is our default plotting library.

When displaying static pages like matplotlib plots, you can use the @savefig pseudo directive.

Important

Make sure to add the “figures/” directory before the name.

Note

You do not need to import verticapy. It is imported by default.

.. ipython:: python

    import verticapy
    @savefig core_vDataFrame_plotting_bar_1.png
    verticapy.vDataFrame({"counts":[1,2,1,2]}).bar("counts")

Note

The suppress is optional if you don’t want to show the code.

For dynamic plots like plotly and highcharts, you can save the plot as html and then use the .. raw:: directive to display.

Important

Make sure to write the custom directory(/project/data/VerticaPy/docs/figures/) before the name when calling the file.

Note

You do not need to import verticapy unless you want to show a different use like import verticapy as vp. It is imported by default.

.. ipython:: python
    :suppress:

    import verticapy as vp
    vp.set_option("plotting_lib","plotly")
    data= vp.vDataFrame({"counts":[1,1,1,2,2,3]})
    fig=data.bar("counts")
    fig.write_html("figures/core_vDataFrame_vDFPlot_bar.html")

.. raw:: html
   :file: /project/data/VerticaPy/docs/figures/core_vDataFrame_vDFPlot_bar.html

Output:

Similarly, we can display the unique VerticaPy table outputs by saving them as html:

.. ipython:: python
    :suppress:

    from verticapy.datasets import load_smart_meters
    sm = load_smart_meters()
    html_file = open("figures/core_vDataFrame_agg_table.html", "w")
    html_file.write(sm._repr_html_())
    html_file.close()

.. raw:: html
    :file: /project/data/VerticaPy/docs/figures/core_vDataFrame_agg_table.html

Notes#

We can also add notes or warning or helpful boxes to get the attention of users. There are many such options for admonitions. Check out https://sphinx-themes.org/sample-sites/furo/kitchen-sink/admonitions/ for the entire list.

But the most basic would be note:

.. note:: Please note that this is a note

Output:

Note

Please note that this is a note