Add example of using custom templates for model cards

[BenjaminBossan]

Once #203 is merged, it would be good to give an example of how to use custom templates for model cards.

This should include how to add the sections that come by default with the default template:

• metrics (when calling card.add_metrics)
• getting started code (automatic)
• model hyperparams
• model plot (automatic if model_diagram=True)

Those are not added by default when using a custom template but it's still possible to add them the normal way (i.e. using card.add), although it's not obvious how. The examples should explain that.

This might also require exposing some convenience functions to the user, e.g. a way to create the sklearn model diagram with a single function call.

[y1450]

Hi @BenjaminBossan, I am new to repo and currently exploring the codebase.
As #203 is merged, Would you suggest this as a "a good first issue" and if so can I work on it.
Thank you for writing such detailed commit messages cc229a2 faf9e37 , they are quite useful for following the implementation.

[BenjaminBossan]

@y1450 First of all, thanks for your comment on the commit messages, I'm happy to learn that at least one person reads them :)

Regarding your initial question, I think it could be a good first issue. Based on the examples that are already in the repo, it should be possible to craft a small example highlighting the differences when working with custom templates. Of course, we can always help and answer questions if you run into any issues (which would also be a good indication that we should document better). So if you're still interested, please give it a try.

This should include how to add the sections that come by default with the default template:

• metrics (when calling card.add_metrics)
• getting started code (automatic)
• model hyperparams
• model plot (automatic if model_diagram=True)

Those are not added by default when using a custom template but it's still possible to add them the normal way (i.e. using card.add), although it's not obvious how. The examples should explain that.

I should add that we made some changes in this regard. After I wrote it, we added a feature that allows pass a description argument to the corresponding methods. This allows to replicate the same behavior as found with the default template.

To give an example, the add_get_started_code method would only add the code block. Thus, if a user wanted to add some text before the code block, they could not use add_get_started_code but had to use add and then wrap the code block in the passed string. This is what I meant in the quote. Now, however, users can use add_get_started_code and pass additional text to the description argument.

https://skops.readthedocs.io/en/stable/modules/classes.html#skops.card.Card.add_get_started_code

The same goes for metrics, hyperparameters and the model diagram.

[y1450]

After exploring the relevant pull request and commits. As per my understanding, there are two ways to add sections using custom templates.

1. use convenience method eg. add_metrics , add_plot (68e4748)
2. use card.add, although I have not yet explored how to add metric or plots

Currently, there is no way to read a template from markdown file,but after the pandoc implementation #257,is finished. Users would be able use custom templates specified through template markdown files.
parsed_card = parse_modelcard("README.md")

I will write an example illustrating the usage. Is there anything I am missing or got wrong, please feel free to correct.

[BenjaminBossan]

Yes, your understanding is correct.

Is there anything I am missing or got wrong, please feel free to correct.

Please go ahead and once you create a PR, we can comment on it. That should be the easiest way.

[BenjaminBossan]

Friendly reminder @y1450. Do you still plan on working on this?

[y1450]

thanks for the reminder, I will complete it over the weekend.

[BenjaminBossan]

@y1450 sorry for one more friendly reminder :) Please also let us know if you don't plan on working on this anymore, there is no obligation.

[y1450]

Thanks for the reminder. Unfortunately I can not work on it anytime soon. I don't want to hang on it to slow down the implementation.