gethelp.py

import streamlit as st


def add_back_button():
    def fn():
        st.session_state.screen.state = "start"

    st.button(
        "Back", help="Get back to the start screen", on_click=fn, key="help_get_back"
    )


help_md = """# Create a Hugging Face model repository for scikit learn models

This page aims to provide a simple interface to use the
[`skops`](https://skops.readthedocs.io/) model card and HF Hub creation
utilities.

## Step 1: Prepare the model repository

In this step, you do the necessary preparation work to create a [model
repository on Hugging Face Hub](https://huggingface.co/docs/hub/models).

### Upload a model

Here you should upload the sklearn model we want to present in the model
repository. The model should be stored either as a ``pickle`` file or it should
use the [secure skops persistence
format](https://skops.readthedocs.io/en/stable/persistence.html). Later, this
model will be uploaded to the model repository so that you can share it with
others.

The uploaded model should be a scikit-learn model or a model that is compatible
with the sklearn API, e.g. using [XGBoost sklearn
wrapper](https://xgboost.readthedocs.io/en/stable/python/python_api.html#module-xgboost.sklearn)
when it's an XGBoost model.

If you just want to test out the application and don't want to upload a model, a
dummy model will be used instead.

### Upload input data

It's possible to upload input data as a csv file. If that is done, the first few
rows of the input data will be used as sample data for the model, e.g. when
trying out the [inference API](https://huggingface.co/inference-api).


### Choose the task type

Choose the type of task that the model is intended to solve. It can be either
classification or regression, with input data being either tabular in nature or
text.

### Requirements

This is the list of Python requirements needed to run the model.

### Choose the model card template

This is the final step and choosing one of the options will bring you to the
editing step.

#### Create a new skops model card

This is the recommended way of getting started. The skops model card template
prefills the model card with some [useful
contents](https://skops.readthedocs.io/en/stable/model_card.html#model-card-content)
that you probably want to have in most model cards. Don't worry: If you don't
like part of the content, you can always edit or delete it later.

#### Create a new empty model card

If you want to start the model card completely from scratch, that's also
possible by choosing this option. It will generate a completely empty model card
for you that you can fashion to your liking.

#### Load existing model card from HF Hub

If you want to use an existing model card and edit it, that's also possible.
Please enter the Hugging Face Hub repository ID here and the corresponding model
card will be loaded. The repo ID is typically someting like `username/reponame`,
e.g. `openai/whisper-small`. Some models also omit the user name, e.g. `gpt2`.

Note that when you choose an existing model card, a couple of files will be
downloaded, because they may be required to render the model card (e.g. images).
Therefore, depending on the repository, this step may take a bit.

If you notice any problems when rendering the existing model card, please let us
know by [creating an issue](https://github.com/skops-dev/skops/issues).

## Step 2: Edit the model card

Before creating the model repository, it is crucial to ensure that the [model
card](https://huggingface.co/blog/model-cards) is edited to best represent the
model you're working on. This can be achieved in the editing step, which is
described in more detail below.

### Editing sidbar

In the left sidebar, you will be able to edit the model card, whereas the main
screen is reserved for rendering the model card so that you see what you will
get. We will start by describing the editing sidebar.

Tip: You should increase the width of the side bar if it is too narrow for your
taste.

#### Undo, redo & reset

On top of the side bar, you have the option to undo, redo, and reset the last
operation you did. Say, you accidentally made a change, just press the `Undo`
button to undo this change. Similarly, if you want to undo your undo operation,
press the `Redo` button. Finally, if you press `Reset`, all your operations will
be undone (but don't worry if you click the button accidentally, you can redo
all of them if you want).

#### Save, create repo & delete

These buttons are intended for when you finished editing the model card. When
you click on `Save`, you will get the option to download the model card as a
markdown file.

When clicking the `Create Repo` button, you will be taken to the next screen,
which offers you to create a model repository on Hugging Face Hub. This step
will be explained in more detail further below.

Finally, you can click on `Delete` to completely discard all the changes you
made and be taken back to the start screen of the app. Be careful, any change
you made will be lost. It is thus advised to first save the model card before
pressing `Delete`.

#### Edit a section

Each section has its own form field, which allows you to make edits. Change the
name of the section or change the content (or both), then click `Update` to see
a preview of your change. As with all other operations, you can undo the change
by clicking on `Undo`.

#### Delete a section

Below the form field for editing the section, you will find a `Delete` button
(including the name of the section to make it clear which section it refers to).
If you click that button, the whole section, _including its subsections_, will
be deleted. Again, click on `Undo` if you accidentally deleted something that
you want to keep.

#### Add section below

If you click on this button, a new subsection wil be created under the current
section. This will create a section with a dummy title and dummy content, which
you can then edit.

Note that this will create a new _subsection_. If there are already existing
subsections in the current section, the new subsection will be created _below_
those existing subsections. So the new subsection you create might not appear
exactly where you expect it to appear. To illustrate this, assume that we have
the following sections and subsections:

- Section A
  - Subsection A.1
  - Subsection A.2
- Section B

If you create a new section below "Section A", it will be created on the same
level, and below of, "Subsection A.2", resulting in the following structure:

- Section A
  - Subsection A.1
  - Subsection A.2
  - NEW SUBSECTION
- Section B

If you create a new section below the "Subsection A.1", you will actually create
a sub-subsection, resulting in the following structure instead:

- Section A
  - Subsection A.1
    - NEW SUB-SUBSECTION
  - Subsection A.2
- Section B

Hopefully, this clarifies things. Unfortunately, there is no possibility (yet)
to re-order sections.

#### Add figure below

This button works quite similarly to adding a new section. The main difference
is that instead of having a text area to enter content, you will be asked to
upload an image file. By default, a dummy image will be shown in the preview.

#### Add metrics (only skops template)

If you have chosen the skops template, you will see an additional field called
`Add metrics` near the top of the side bar. Here you can choose metrics you want
to be shown in the model card, e.g. the accuracy the model achieved on a
specific dataset. Please enter one metric per line, with the metric name on the
left, then an `=` sign, and the value on the right, e.g. `accuracy on test set =
0.85`.

After pressing `update`, the metrics will be shown in a table in the section
`Model description/Evaluation Results`. You can always add or remove metrics
from this field later. If you want to delete this section completely, look for
its edit form further below and press `Delete`. There, you can also edit the
table in a more fine grained way, e.g. by changing the alignment.

If you don't use the skops template and still want to add a table, it is
possible to do that, but it's requires a bit more work. Add a new section as
described above, then, in the text area, create a table using the [markdown
table
syntax](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables#creating-a-table).

### Model card visualization

The main part of the page will show you what the final model card will look
like.

#### Metadata

On the very top, you can see the metadata of the model card (it is collapsed by
default). The metadata can be very useful for features on the HF Hub, e.g.
allowing other users to find your model by a given tag.

Right now, it is not possible to edit the metadata directly from here. But don't
worry, once you have created the model card repository, you can easily edit the
metadata there.

#### Table of Contents

For your convenience, a table of contents is also shown at the top (collapsed by
default). This is useful if you have a bigger model card and want to see the
overview of all its contents.

#### Markdown preview

Finally, the model card itself is shown. This is how the model card will look
like once it is saved as markdown and then rendered.

## Step 3: Creating a model repository

After you have finished editing the model card, it is time to create a model
repository on Hugging Face Hub. Click on `Create Repo` and you will be taken to
the final step of the process.

### Back & Delete

If you find yourself wanting to make more edits to the model card, just click on
the `Back` button and you'll be brought back to the editing step.

You can also click `Delete`, which will discard all your changes and bring you
back to the start page. Be careful: This step cannot be undone and all your
progress will be lost.

### Files included in the repository

For your convenience, this will show a preview of all the files included in the
repository, as well as their sizes. Don't create a repository if you see files
there that you don't want to be uploaded.

### Privacy settings

By default, a private repository will be created. If you untick this box, it
will be public instead. More information on what that implies can be found in
the [docs on repository
settings](https://huggingface.co/docs/hub/repositories-settings).

### Name of the repository

Here you have to enter the name of the repository. Typically, that's something
like `username/reponame` or `organame/reponame`. This field is mandatory and you
should ensure that the corresponding repository ID does not exist yet.

### Enter your Hugging Face token

Here you need to paste your Hugging Face token, which is used for
authentication. The token can be found [here](https://hf.co/settings/token) and
it always starts with "hf_". Entering a token is necessary to create a
repository.

Note that if you don't already have an account on Hugging Face, you need to
create one to get a token. It's free.

### Create a new repository

Once all the required fields are filled, click on this button to create the
repository. Depending on the size, it may take a couple of seconds to finish.
Once it is created, you will see a success notification that includes the link
to the repository. Congratulations, you're done!

## Troubleshooting

### Not all skops features available

This app is based on the [skops model card
feature](https://skops.readthedocs.io/en/stable/model_card.html#model-card-content).
However, it does not support all the options that are available there. If you
want to use all those options in a programmatic fashion, please follow the link
and read up on what it takes to create a model card with skops. The full power
of the `Card` class is documented
[here](https://skops.readthedocs.io/en/stable/modules/classes.html#skops.card.Card).

### Strange behavior

If the app behaves strangely, shows error messages, or renders incorrectly, it
may be necessary to refresh the browser tab. This will take you back to the
start page, with all progress being lost. If you can reproduce that behavior,
please [creating an issue](https://github.com/skops-dev/skops/issues) and let us
know.

### Contact

If you want to contact us, you can join our discord channel. To do that, follow
[these
instructions](https://skops.readthedocs.io/en/stable/community.html#discord).
"""


def add_help_content():
    # This is the exact same text as in the README.md of this space
    st.markdown(help_md)


def help_page():
    add_back_button()
    add_help_content()