search

dsa-ou / algoesup

Algorithmic essays support: examples, templates, guides, library
https://dsa-ou.github.io/algoesup/
BSD 3-Clause "New" or "Revised" License
2 stars 0 forks source link

Replace Just the Docs with MkDocs #13

Closed mwermelinger closed 8 months ago

mwermelinger commented 8 months ago

MkDocs has a large catalogue of plugins, including for generating API docs and using Jupyter notebooks, so it may be a better bet for the future than Just the Docs, which doesn't seem to have any plugins and has a smaller community of developers.

Another advantage is that MkDocs doesn't require ruby, gems and Jekyll. It's all Python to generate static sites. Makes it easier for others to contribute.

I do prefer the font, buttons and admonitions (callouts) of Just the Docs, but we can style MkDocs later if we want. (I used the material theme.)

I've converted our docs to MkDocs, just minor changes: blank lines before lists, indent by 4 always, change the syntax for call outs. I've added a dark theme and the current algoesup.py docstrings.

To see the resulting static pages, run pip install -r requirements.txt to pick up the new packages and then mkdocs serve. Let me know what you think.

densnow commented 8 months ago

Found this plugin for mkdocs to open external links (and PDFs) in new tabs, which might be useful for us. We could either add it as dependency, or borrow some of the code (with attribution) and hardwire it into the project.

mwermelinger commented 8 months ago

The notebooks are now rendered as part of the docs, which is more environmentally friendly than rendering on demand on nbviewer or GH. You will have to re-run pip to pickup the two new mkdocs plugins.

I've experimented with integrating the TOC of each page within the navigation panel, to save space for smaller screens, but I think it can get a bit confusing. Reverted to separate nav and TOC panels. Made nav panel fixed (no collapsing headings). I also tried sections in the header, but then you always have to scroll to the top of the page to go to a different section. I think the current configuration is the easiest to go directly from any page to any other page.

Please do check things and, if everything's OK, do squash and merge. Thanks.

densnow commented 8 months ago

@mwermelinger The .github/workflows/pages.yml is still set up for jekyll. We can delete this right?

densnow commented 8 months ago

Anyway, I guess that can all be sorted when you deploy the site. The notebooks seem to render nicely and no problems anywhere else AFAIK. I will go ahead and with the squash and merge now.