Autogenerate documentation from custom python classes

pdoc3 - installation, generation, browse documentation
python
Published

June 30, 2021

Installation

!conda env list
# conda environments:
#
base                     /home/explore/miniconda3
aniti                    /home/explore/miniconda3/envs/aniti
audioclass               /home/explore/miniconda3/envs/audioclass
coursera_rl              /home/explore/miniconda3/envs/coursera_rl
d059                  *  /home/explore/miniconda3/envs/d059
datacamp                 /home/explore/miniconda3/envs/datacamp
deeplearning_specialization     /home/explore/miniconda3/envs/deeplearning_specialization
deeplearning_specialization_keras     /home/explore/miniconda3/envs/deeplearning_specialization_keras
deeplearning_specialization_tf1     /home/explore/miniconda3/envs/deeplearning_specialization_tf1
drl_handson              /home/explore/miniconda3/envs/drl_handson
drl_simonini             /home/explore/miniconda3/envs/drl_simonini
fastai                   /home/explore/miniconda3/envs/fastai
fastaudio                /home/explore/miniconda3/envs/fastaudio
gan                      /home/explore/miniconda3/envs/gan
gan_tensorflow           /home/explore/miniconda3/envs/gan_tensorflow
macos                    /home/explore/miniconda3/envs/macos
minecraft                /home/explore/miniconda3/envs/minecraft
mit_6002x                /home/explore/miniconda3/envs/mit_6002x
mit_6S191                /home/explore/miniconda3/envs/mit_6S191
pycaret                  /home/explore/miniconda3/envs/pycaret
pytorch                  /home/explore/miniconda3/envs/pytorch
scikit-learn-course      /home/explore/miniconda3/envs/scikit-learn-course
shap                     /home/explore/miniconda3/envs/shap
squeezebox               /home/explore/miniconda3/envs/squeezebox
stablebaselines3         /home/explore/miniconda3/envs/stablebaselines3
zoe                      /home/explore/miniconda3/envs/zoe
import sys
!conda install --yes --prefix {sys.prefix} pdoc3
Collecting package metadata (current_repodata.json): done
Solving environment: / 
The environment is inconsistent, please check the package plan carefully
The following packages are causing the inconsistency:

  - defaults/linux-64::matplotlib==3.3.2=0
  - defaults/linux-64::matplotlib-base==3.3.2=py38h817c723_0
  - defaults/linux-64::spacy==2.3.2=py38hfd86e86_0
  - pytorch/linux-64::torchvision==0.8.1=py38_cu110
  - defaults/linux-64::numpy==1.19.2=py38h54aff64_0
  - defaults/linux-64::thinc==7.4.1=py38hfd86e86_0
  - defaults/linux-64::cython-blis==0.4.1=py38h7b6447c_1
  - fastai/noarch::fastprogress==1.0.0=pyh39e3cac_0
  - fastai/noarch::fastai==2.1.4=py_0
  - defaults/linux-64::mkl_random==1.1.1=py38h0573a6f_0
  - pytorch/linux-64::pytorch==1.7.0=py3.8_cuda11.0.221_cudnn8.0.3_0
  - defaults/linux-64::pandas==1.1.3=py38he6710b0_0
  - fastai/noarch::fastscript==1.0.0=0
  - defaults/linux-64::scipy==1.5.2=py38h0b6359f_0
  - defaults/linux-64::mkl_fft==1.2.0=py38h23d657b_0
  - fastai/noarch::fastbook==0.0.14=py_0
  - defaults/linux-64::scikit-learn==0.23.2=py38h0573a6f_0
done

## Package Plan ##

  environment location: /home/explore/miniconda3/envs/d059

  added / updated specs:
    - pdoc3


The following NEW packages will be INSTALLED:

  mako               pkgs/main/noarch::mako-1.1.4-pyhd3eb1b0_0
  markdown           pkgs/main/linux-64::markdown-3.3.4-py38h06a4308_0
  pdoc3              pkgs/main/noarch::pdoc3-0.9.2-pyhd3eb1b0_0

The following packages will be UPDATED:

  ca-certificates                              2020.10.14-0 --> 2021.5.25-h06a4308_1
  certifi            pkgs/main/noarch::certifi-2020.6.20-p~ --> pkgs/main/linux-64::certifi-2021.5.30-py38h06a4308_0
  mkl_fft                              1.2.0-py38h23d657b_0 --> 1.3.0-py38h54f3939_0
  openssl                                 1.1.1h-h7b6447c_0 --> 1.1.1k-h27cfd23_0
  scipy                                1.5.2-py38h0b6359f_0 --> 1.6.2-py38h91f5cce_0


Preparing transaction: done
Verifying transaction: done
Executing transaction: done

Generate documentation from .py files

!pdoc --html --output-dir /home/explore/git/guillaume/d059/exp/html /home/explore/git/guillaume/d059/exp/init_D059.py
/home/explore/git/guillaume/d059/exp/html/init_D059.html

This is the way to generate doc:

pdoc --html --output-dir exp/html exp/my_classe.py

force refresh of doc

in case of existing html file

pdoc --html --output-dir exp/html --force exp/my_classe.py

Example

Proper docstring to get nice output

Here is an example that gives good result:

    """
    Un wrapper de lecture de contenu.
    En fonction de la nature du fichier (extension), appelle le bon lecteur.
    Les extensions supportées sont :
        - .csv : pour appel à pd.read_csv. (Les colonnes Unnamed seront supprimées)
        - .xls, .xlsx : pour appel à pd.read_excel
        - .accdb : pour appel à pd.read_sql (disponible uniquement sous Windows)
    Prend en parametre le nom complet du fichier csv, avec son extension. Et les options à passer.
    Si un nom de colonne contient Date, le type datetime64 est appliqué.
    Renvoie le dataframe correspondant.

    Examples
    --------
    >>> getRawContent(root_data+'Stam-CC/MCCSC 25625.csv', sep=';', decimal=',', dayfirst=True)
    >>> getRawContent(root_data+'Stam-CC/ExportData 25625.xlsx', sheet_name='ExportData 25625 MCCS')
    >>> getRawContent(root_data +  '/accessDB/Datos 19_12.accdb', tablename='Datos_GR02_25625')

    Parameters
    ----------
    filename : string
        Emplacement du fichier. Format complet avec l'extension
        Ex: root_data+'Stam-CC/MCCSC 25625.csv'
    options : **keyword args, optional
        Arguments valides dans l'appel à pandas.read_csv, ou pandas.read_excel, ou pandas_read_sql : https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html
        Ex: sep=';', decimal=',', dayfirst=True
        Ex: **{'sep':';', 'decimal':',', 'dayfirst':True}

    Returns
    -------
    dataframe
        Dataframe correspondant au filename avec les options de lecture associées.
    """

that results as

pdoc docstring