Skip to content

Migrate documentation to mkdocs + various improvements#116

Merged
davidwyld merged 13 commits intomainfrom
dw/mkdocsdocs
Jan 28, 2026
Merged

Migrate documentation to mkdocs + various improvements#116
davidwyld merged 13 commits intomainfrom
dw/mkdocsdocs

Conversation

@davidwyld
Copy link
Contributor

@davidwyld davidwyld commented Jan 28, 2026

Resolves #112

  • Migrates from sphinx to mkdocs-material
  • Restructures the docs, reducing nesting etc.

There's still a fair bit to do here:

  • Some repetition across the dataloaders, e.g. similar content in scalar, vector and LUT dataloader pages which could be consolidated,
  • There's probably more we can do with automatic documentation from docstrings, particularly with the dataloaders (also see Review dataloaders #113) - there's a lot of extra information in the docs for each dataloader, some of which I like, but could maybe be kept in the dataloader docstrings themselves and be rendered in the autoapi docs?
  • Quite a lot of typos and spelling errors throughout the docstrings which we could sort out.
  • In many places the docs are a bit verbose for my tastes, though this is personal preference.
  • There's a lot of documentation, which is great! But perhaps I could tidy it up a bit more in places.
  • There are a lot of warnings from mkdocstrings/autoapi right now but when Adding typehints #108 is merged in, hopefully most will be resolved.

Note: Merge target is set to github-pages-docs for now to keep the diff relevant, but we should really get that branch merged soon and this can target main instead.

@thomaszwagerman
Copy link
Contributor

Things you love to see:

  • it

Copy link
Contributor

@thomaszwagerman thomaszwagerman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great. Quite a few warnings from griffe, but as you say, we can tackle those and they aren't necessarily to do with the docs themselves, rather the docstrings.

Base automatically changed from github-pages-docs to main January 28, 2026 12:37
@davidwyld davidwyld marked this pull request as ready for review January 28, 2026 13:16
@davidwyld davidwyld merged commit 55e1559 into main Jan 28, 2026
1 check failed
@davidwyld davidwyld deleted the dw/mkdocsdocs branch January 28, 2026 13:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Convert docs from sphinx to mkdocs

2 participants