Welcome to the PyPI Blog | Hacker News Reader

Welcome to the PyPI Blog

blog.pypi.org

55 pointswoodruffw9 comments

Importantly, they did not leave a link for how one might volunteer. I had no idea they were looking for help, and now that I know they need help I want to know more.

Perhaps that'll be a future blog post. Also, https://github.com/pypi/warehouse seems a good place to start.

The footer at that page says the site uses MkDocs [1]. Has anyone used it and knows how it compares to Sphinx and MyST-Parsee [2]?

[1]: https://www.mkdocs.org/

[2]: https://www.sphinx-doc.org/en/master/usage/markdown.html

I've used both MkDocs and Sphinx, and had better experience with the former. Sphinx is more powerful, I guess, but for my purposes MkDocs was enough, and it is much simpler to set up right. The Material theme [1] is very nice, looks good and search works out of the box.

Thanks for reminding me about this, I haven't looked at Material theme for a while, and it seems like they have some nice new features like code annotations [2]. Back when I was using this theme for some educational materials this feature would've been very useful to me.

[1]: https://squidfunk.github.io/mkdocs-material/ [2]: https://squidfunk.github.io/mkdocs-material/reference/code-b...

Mkdocs has quite a good ecosysten especially around Mkdocs Material[0] used by projects like FastApi[1].

Mkdocs is quite easy to setup and has features comparable to Sphinx and MyST-Parse. Iirc it has less stuff out of the box compared to Sphinx but nakes up for it with a mature plugin ecosystem.

[0]: https://squidfunk.github.io/mkdocs-material/ [1]: https://fastapi.tiangolo.com/

Thanks for the brief comparison and for the links!

Sphinx is powerful and hard to beat if you're looking to generate documentation from code in multiple languages or export to multiple document formats, but it's slow and creaky and hard to hack on.

MkDocs by itself is okay, but Material for MkDocs is life-changing:

https://squidfunk.github.io/mkdocs-material/

If it does everything you need it to do, it'll make creating and editing sites much faster and with fewer opportunities to break things.

I'm not familiar with Sphinx/MyST. Textual (https://textual.textualize.io/) uses MkDocs - I especially like the search feature.

I am using Sphinx with MyST as I had seen it being used in the JupyterHub.

I have textual on my bookmarks (have a future task to write a TUI for an app and need to choose between urwid and textual/rich [for HPC - ie older OS, lots of security measures around the terminal and access]).

I did a quick search but looks like I cannot use Sphinx directives with MkDocs [1].

I will search some more after coffee break, but there are directives I am using in other Sphinx (reSt and myst-md) that I would prefer to keep using if possible (I've also modified and monkey-patched some directives and loaded locally with sphinx/py).

Thanks

[1]: https://github.com/mkdocs/mkdocs/discussions/2390

Reply on news.ycombinator.com