Build a complete documentation for ipyvuetify

[12rambau]

Rational

It's been several years now that i've been using the ipyvuetify to build succesfull dashboard and I must confess that with the release of Solara I was delighted to see I can now deploy them outside of a jupyter server context freeign from lots of issues I faced in the past.

The one major drawback that I faced in this timeframe is the difficulty to train pure python data scientist, or pure python developer into using this lib. The main blocker for them was the absence of documentation of components in Python. To use the lib you need to first understand the vue scripting mechanism and then understand the way ipyvuetify wire everything together. It's too long of a process for most. So I decided to embark myself again on this crusade of building a full documentation for the lib. By doing so I realized that reproducing all the exemple from the original doc is also challenging even for a seasoned user like myself making it even more relevant (I think).

The pre-build of the documentation can be found here: https://ipyvuetify-docs-test.readthedocs.io/en/latest/

I tried 2 years ago to perfomr the same exercice and it never went through as our presence in the open source space was out of sync, this time I will propose a complete thing even if sometime I go a bit sideway from what you would have coded yourself

Modifications

Complete Class Blueprints

THe class were simply stating **kwargs until now preventing anyone to know what parameter were available until they got to the ipyvuetify documentation. In this PR I edited the python.njk file to add multiple information:

• the parameters in the init function
• the parameters in the docstring
• a dedicated docstring for each trait (which is obviously the same as the parameters)

it produces classes like this:

from traitlets import (
    Unicode, Enum, Instance, Union, Float, Int, List, Tuple, Dict,
    Undefined, Bool, Any
)

from .VuetifyWidget import VuetifyWidget


class Alert(VuetifyWidget):

    _model_name = Unicode('AlertModel').tag(sync=True)

    outlined = Bool(None, allow_none=True).tag(sync=True)
    """Makes the background transparent and applies a thin border."""

   # [...] all the other traits of course 


    def __init__(self, outlined=None, **kwargs):
        """Initialize an instance of Alert that can be added to the DOM.

        The v-alert component is used to convey important information to the user through contextual types, icons, and colors. These alerts are positioned to draw user attention.

        Arguments:
            prominent: Displays a larger vertically centered icon to draw more attention.
            [...]
            **kwargs: Additional keyword arguments passed to the parent class.

        Returns:
            An instance of Alert that can be added to the DOM.
        """
        super().__init__(outlined=outlined, **kwargs)

__all__ = ['Alert']

Considering that the version of vuetify we use is 2.2.26 I could not find a proper documentation available on the web so I tried to gather as much as possible meaningful things from the 2.7.2 (last v2 available website). When moving to v3 the documentation is much more integrated to the API and will be much easier to gather. I added them as docs key for the component and their members in generate_source/vuetify_api.json.

Custom PyData Theme for API

To display the documentation, I went for the pydata sphinx theme and small extentions for the sphinx interface:

• sphinx.ext.napoleon: To read the Google styled docstrings
• sphinx.ext.autosectionlabel: to reference other internal pages easily
• sphinx.ext.todo: to add todo admonition in the component pages when the parameter is not yet supported
• jupyter_sphinx: to create the executed exemples
• sphinx_design: to add the tab system in the exemple sections
• autoapi.extension: to document automatically the API
• sphinx_copybutton: to make code reference copyable
• sphinx_last_updated_by_git: to show when the page was last updated based on it's git signature

I also created for the navabar a python version of the ipyvuetify logo and used a nice looking OSS font to match the vuetify look and feel:

Dedicated Component Pages

I refctored heavily the documentation structure to match what a new user would be looking for:

• the old documentation with the main principle has been entirely moved to a "getting started" section
• the component section showcase countless exemples in both Python and vuetify template style
• the API reference show the content of the class in more classic way

landing	usage	component	API

Each component is given a dedicated page. As we are out of sync with the current version of ipyvuetify I based everything on the version 2.7.2 of the doc that is the last published v2 available website. I could not copy all of the exemple as some trait are not available in the 1.13 version of ipyvuetify. also as the kernel is not active in the static documentation the interaction is very difficult to showcase. My take is that it's already a huge advantage to get the written exemple, finding a better alternative to jupyter-spinx can be taken cared of in a follow-up PR.

TODO

• finish documenting every component individually
• review all the component API descriptions and fill the missing ones
• reorganized the component documentation sections (they are currently in alphabitcal order)
• fill the intermediary pages with expalinations (specifically the component.rst one)
• move all the exemple code in dedicated files for linting (I keep them where they are now to provide as much context as possible to copilot when he tries to guess)
• add a disclaimerr banner
• review as much example as possible

linked issues

Fix #268
Fix #180
Fix #13