DOC User guide for model cards (#70)

Co-authored-by: Benjamin Bossan <BenjaminBossan@users.noreply.github.com>

docs/index.rst

@@ -21,7 +21,9 @@ The following examples are good starting points:
   :ref:`sphx_glr_auto_examples_plot_model_card.py`
 
 In order to better understand the role of each file and their content when
-uploaded to Hugging Face Hub, refer to this :ref:`user guide <hf_hub>`.
+uploaded to Hugging Face Hub, refer to this :ref:`user guide <hf_hub>`. You can
+refer to :ref:`user guide <model_card>` to see how you can leverage model cards
+for documenting your scikit-learn models and enabling reproducibility.
 
 User Guide / API Reference
 ==========================
@@ -30,6 +32,7 @@ User Guide / API Reference
    :maxdepth: 2
 
    hf_hub
+   model_card
    modules/classes
 
 

docs/model_card.rst

@@ -0,0 +1,58 @@
+.. _model_card:
+
+Model Cards for scikit-learn
+============================
+
+This library allows you to automatically create documentation for models, also
+known as model cards. The specifications of the model cards and tools to create
+them depend on the format `Hugging Face Hub <https://huggingface.co/>`__ expects
+them to comply with. This format consist of two parts, a metadata part for model
+discoverability and markdown part for information related to model. Hub expects
+the card to be a markdown file called ``README.md``.
+
+The metadata part of the file needs to follow the notation `here
+<https://huggingface.co/docs/hub/models-cards#model-card-metadata>`__. It
+includes simple attributes of your models such as the task you're solving,
+dataset you trained the model with, evaluation results and more. When the model
+is hosted on the Hub, information in metadata like task name or dataset help
+your model be discovered at the `Hugging Face Hub
+<https://huggingface.co/models>`__. The task identifiers should follow the task
+taxonomy defined in Hugging Face Hub, as it enables the inference widget on the
+model page. An example to task identifier can be ``"tabular-classification"`` or
+``"text-regression"``.
+
+An example metadata part looks like below:
+
+.. code-block:: yaml
+
+    ---
+    library_name: sklearn
+    tags:
+    - tabular-classification
+    license: mit
+    datasets:
+    - breast-cancer
+    metrics:
+    - accuracy
+    ---
+
+The markdown part does not necessarily need to follow any specification by means of
+information passed, which gives the user a lot of flexibility. The markdown part
+of the card is generated from templates with slots that you can inject your
+content in. ``skops`` has a default template called ``default_template.md``.
+
+``default_template.md`` includes the following for free text sections:
+
+- model_description: Simple description of the model,
+- limitations: Intended use for the model, limitations and biases,
+- get_started_code: Code the user can run to load and use the model,
+- model_card_authors: Authors of the model card,
+- model_card_contact: Contact information to reach out to the model card authors,
+- citation_bibtex: Citation for the resources used to train the model.
+
+The template also contains following sections that are automatically generated by ``skops``.
+
+- hyperparameter_table: Hyperparameters of the model.
+- model_plot: Plot of the model.
+
+If you want a custom template, you can pass the ``template_path`` with :meth:`.Card.add`.