Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate documentation from Sphinx to Mkdocs #1075

Open
ns-rse opened this issue Jan 21, 2025 · 0 comments
Open

Migrate documentation from Sphinx to Mkdocs #1075

ns-rse opened this issue Jan 21, 2025 · 0 comments

Comments

@ns-rse
Copy link
Collaborator

ns-rse commented Jan 21, 2025

Currently we use Sphinx to build and render the website with ther
myst_parser extension which allows us to write Markdown
documents and include them in the index.rst.

For another project IsoSLAM I've recently switched to using
Mkdocs for rendering the website (see
here). It uses Markdown natively and was
very easy to setup and configure. In particular setting up
versioning is much more straight-forward
than the current system using sphinx-multiversion which
relies on a tweak I had to make to a fork of the action/spinx-docs-to-gh-pages (see
ns-rse/action-sphinx-docs-to-gh-pages for that fork).

The rendering of the API in particular is very nice (although it does require excluding the API Markdown files from
being linted by prettier by adding them to .prettierignore).

Low priority (I'm working through #517 components at the moment) but I'd estimate its a few hours work to do this
migration but would be worthwhile as going forward it gives a cleaner system to work with, extend and maintain and worth
doing before my time on TopoStats ends in a few months.

There are plenty of themes to choose from, let me know if there
are any favourites (its simple to switch though).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant