add mkdocs documentation

[roman807]

closes #77

Adds basic mkdocs documentation, following the example of FastAPI (see: documentation, repo)

To review, run

pdm update
mkdocs serve

and check

• http://127.0.0.1:8000/
• http://127.0.0.1:8000/reference/

[nkaenzig]

Looks good, I'm getting this error though:

(eva-3.10) ➜  eva (77-add-mkdocs-documentation) mkdocs serve                                                                                ✭ ✱
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - reference.md
ERROR   -  mkdocstrings: src.eva.vision.data.datasets.vision could not be found
ERROR   -  Error reading page 'reference/vision.md':
ERROR   -  Could not collect 'src.eva.vision.data.datasets.vision'

[roman807]

Looks good, I'm getting this error though:

(eva-3.10) ➜  eva (77-add-mkdocs-documentation) mkdocs serve                                                                                ✭ ✱
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - reference.md
ERROR   -  mkdocstrings: src.eva.vision.data.datasets.vision could not be found
ERROR   -  Error reading page 'reference/vision.md':
ERROR   -  Could not collect 'src.eva.vision.data.datasets.vision'

the __init__.py files were missing. can you try again?

[nkaenzig]

@roman807 Now it works! This looks good. I briefly compared it with the fastAPI docs and noted the following:

1. For the parameters they have tables, which I think look nicer and are more compact:

2. They have these nicely formatted examples. Apparently they come directly from the docstrings. Does our setup support this?

3. They don't have the expandable boxes to display the source code (do we want to have this?)

[roman807]

@nkaenzig re your 3 comments from above:

(1) added the parameter tables, they are not identical to fastAPI's example, but more comprehensive (columns: name, type, description, default)

(2) yes, we will have to add such examples to the docstrings

(3) i see they have expandable source code boxes as well, e.g.: https://fastapi.tiangolo.com/reference/parameters/

[ioangatop]

Looks good! We can start iterating an build from this commit, as I'm not as well are super fluent of mkdocs

when we address @nkaenzig points, lets merge it!

[nkaenzig]

@roman807 Regarding 1), the last thing I'm noticing is that in our docs, the parameters table appears in the end (after listing all the properties & methods). Is it possible to move this to the beginning like this?

[roman807]

@roman807 Regarding 1), the last thing I'm noticing is that in our docs, the parameters table appears in the end (after listing all the properties & methods). Is it possible to move this to the beginning like this?

@nkaenzig the table appears immediately after the method (e.g. the parameters to the method from_metrics appear after the description from the docstring. I think you meant the class- parameters (init args)? Those are currently not displayed at all, because __init__ is a private function and all params belonging to private functions are filtered out.

What FastAPI does is annotating those arguments with typing_extensions.Annotated. I'd propose we add this later.

[nkaenzig]

@roman807 Got it, yes seems that I was confusing the init with public methods. Displaying the __init__ and what arguments it expects would be very nice, but it's fine with me to address this later, can we create an issue for it?

[nkaenzig]

LGTM

[roman807]

@roman807 Got it, yes seems that I was confusing the init with public methods. Displaying the __init__ and what arguments it expects would be very nice, but it's fine with me to address this later, can we create an issue for it?

yes i created an issue: #83