FEAT Parse model cards with pandoc

.github/workflows/build-test.yml

@@ -61,6 +61,9 @@ jobs:
           then pip install --pre --extra-index https://pypi.anaconda.org/scipy-wheels-nightly/simple scikit-learn;
           else pip install "scikit-learn~=${{ matrix.sklearn_version }}";
         fi
+        if [ ${{ matrix.os }} == "ubuntu-latest" ];
+          then wget -q https://github.com/jgm/pandoc/releases/download/2.19.2/pandoc-2.19.2-1-amd64.deb && sudo dpkg -i pandoc-2.19.2-1-amd64.deb;
+        fi
         python --version
         pip --version
         pip list

.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
         exclude: .github/conda/meta.yaml
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
+        exclude: skops/card/tests/examples
     -   id: check-case-conflict
     -   id: check-merge-conflict
 -   repo: https://github.com/psf/black

docs/changes.rst

@@ -9,6 +9,14 @@ skops Changelog
     :depth: 1
     :local:
 
+v0.5
+----
+- :class:`.card.Card` now allows to add content to existing sections, using a
+  ``/`` to separate the subsections. E.g. use ``card.add(**{"Existing
+  section/New section": "content"})`` to add "content" a new subsection called
+  "New section" to an existing section called "Existing section". :pr:`203` by
+  `Benjamin Bossan`_.
+
 v0.4
 ----
 - :func:`.io.dump` and :func:`.io.load` now work with file like objects,
@@ -21,11 +29,6 @@ v0.4
   :pr:`242` by `Merve Noyan`_.
 - Persistence now supports bytes and bytearrays, added tests to verify that
   LightGBM, XGBoost, and CatBoost work now. :pr:`244` by `Benjamin Bossan`_.
-- :class:`.card.Card` now allows to add content to existing sections, using a
-  ``/`` to separate the subsections. E.g. use ``card.add(**{"Existing
-  section/New section": "content"})`` to add "content" a new subsection called
-  "New section" to an existing section called "Existing section". :pr:`203` by
-  `Benjamin Bossan`_.
 
 v0.3
 ----

docs/model_card.rst

@@ -11,6 +11,9 @@ beginning of it, following with the content of the model card in markdown
 format. The metadata section is used to make models searchable on the Hub, and
 get the inference API and the widgets on the website working.
 
+Metadata
+--------
+
 The metadata part of the file needs to follow the specifications `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,
@@ -40,6 +43,9 @@ Here's an example of the metadata section of the ``README.md`` file:
 ``skops`` creates this section of the file for you, and you almost never need
 to touch it yourself.
 
+Model Card Content
+------------------
+
 The markdown part does not necessarily need to follow any specification in
 terms of information passed, which gives the user a lot of flexibility. The
 markdown part of the ``README.md`` file comes with a couple of defaults provided
@@ -90,8 +96,8 @@ as well as adding some subsections with plots below that, you can call the
     })
 
 Furthermore, you can select existing sections (as well as their subsections)
-using :meth:`Card.select`, and you can delete sections using
-:meth:`Card.delete`:
+using :meth:`.Card.select`, and you can delete sections using
+:meth:`.Card.delete`:
 
 .. code-block:: python
 
@@ -103,3 +109,43 @@ using :meth:`Card.select`, and you can delete sections using
 
 To see how you can use the API in ``skops`` to create a model card, please
 refer to :ref:`sphx_glr_auto_examples_plot_model_card.py`.
+
+Saving and Loading Model Cards
+------------------------------
+
+Once you have finished creating and modifying the model card, you can save it
+using the :meth:`.Card.save` method:
+
+.. code-block:: python
+
+    card.save("README.md")
+
+This renders the content of the model card to markdown format and stores it in
+the indicated file. It is now ready to be uploaded to Hugging Face Hub.
+
+If you have a finished model card but want to load to make some modifications,
+you can use the function :func:`skops.card.parse_modelcard`. This function
+parses the model card back into a :class:`.Card` instance that you can work on
+further:
+
+.. code-block:: python
+
+    from skops import card
+    model_card = card.parse_modelcard("README.md")
+    model_card.add(**{"A new section": "Some new content"})
+    model_card.save("README.md")
+
+When the card is parsed, some minor details of the model card can change, e.g.
+if you used different column alignment than the default, this could change, as
+well as removing excess empty lines or trailing whitespace. However, the content
+itself should be exactly the same. All known deviations are documented in the
+`parse_modelcard docs
+<https://skops.readthedocs.io/en/stable/modules/classes.html#skops.card.parse_modelcard>`_
+
+For the parsing part, we rely on `pandoc <https://pandoc.org/>`_. If you haven't
+installed it, please follow `these instructions
+<https://pandoc.org/installing.html>`_. The advantage of using pandoc is that
+it's a very mature library and that it supports many different document formats.
+Therefore, it should be possible to parse model cards even if they use a format
+that's not markdown, for instance reStructuredText, org, or asciidoc. For
+saving, we only support markdown, though.

skops/card/__init__.py

@@ -1,3 +1,4 @@
 from ._model_card import Card, metadata_from_config
+from ._parser import parse_modelcard
 
-__all__ = ["Card", "metadata_from_config"]
+__all__ = ["Card", "metadata_from_config", "parse_modelcard"]