Documentation page using mkdocs

[cgarciae]

Hey, I've been using Einops, loving it.

I thought it would be cool for the project to have a Reference API page so I ported some mkdocs boilerplate files from a Jax library I maintain. Its very basic, you can improve upon it. Check a preview of the site here.

Features

• Readme as the main page.
• All 3 tutorial rendered with mkdocs-jupyter.
• Reference API for:
  • asnumpy
  • parse_shape
  • rearrange
  • reduce
  • repeat

The only change to the core code I made is converting the docs from Numpy-style to Google-style + markdown since that is what mkdocs supports.

Local serving

You can test the site locally via:

bash scripts/run-docs.sh

Deployment

You can deploy the docs to the github.io site with:

bash scripts/deploy-docs.sh

Dev Dependencies

For this I used:

mkdocs = "^1.1.2"
mkdocs-material = "^6.1.0"
mkdocstrings = "^0.13.6"
mkdocs-jupyter = "^0.15.1"

I can add the files for a poetry project I used if you wish.

[arogozhnikov]

Sorry for delay, this looks amazing!

Some comments:

• mkdocs-jupyter - wow, didn't know about that

Can we keep current format of code in docstrings? Like

"""
>>> 1 + 2
3
"""

Because this way it gets tested.

[cgarciae]

Hey, I added the >>> back, I thought they screwed the formatting but works perfectly:

https://cgarciae.github.io/einops/api/rearrange/

I left some white spaces between groups of code for readability, should I remove them?

[arogozhnikov]

Voila!
https://arogozhnikov.github.io/einops

Will try to find some time during weekend to get better formatting for the website

[arogozhnikov]

@cgarciae kudos for showing mkdocs and setting it up!

[cgarciae]

Awesome!

Check out Mkdocs Material which is doing most of the heavy lifting for the aesthetics.