self-contained-runnable-python-package-template VS mkdocs-material

The approach I prefer is to not mess with setuptools etc at all in the first place, and simply make a nice executable package.

e.g. https://github.com/tpapastylianou/self-contained-runnable-py...

The title should be: How to create a "Python DISTRIBUTION package".

The term "python package" means something entirely different (or at the very least is ambiguous in a pypi/distribution context).

To add to the confusion, creating a totally normal, runnable python package in a manner that makes it completely self-contained such that it can be "distributed" in a standalone manner, while still being a totally normal boring python package, is also totally possible (if not preferred, in my view).

Shameless plug: https://github.com/tpapastylianou/self-contained-runnable-py...

Shameless plug: I use my own template, which organises things as runnable projects.

https://github.com/tpapastylianou/self-contained-runnable-py...

It serves my purposes very well (which is creating projects that represent standalone experiments).

Sharing in case someone else here finds it useful.

More recently I've modified this a bit to also generate nice html reports straight from the __main__.py file, independently of the underlying python code, and use this as lab books (where each lab book contains a single analysis and its report). I'll upload this template separately when I find the time.

Material Mk-Docs by Martin Donath works well if you prefer python.

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

I'm an 'outsider', but from from the outside the Material For MkDocs Project looks like a very well managed open source project.

Martin Donath's project uses a 'sponsorware' release strategy to generate donations.

From my vantage point it seems to be working pretty well.

I just recently went through this decision process. My aim is to write code and math oriented posts so I need good support for nice syntax highlighting (at least colored) and mathjax (preferable) or katex. Substack is the most popular newsletter platform but fails at these two criteria. I love how math and syntax highlighting (plus numerous other features) work in MkDocs Material, which recently added a Blog plugin.

I wanted to combine the best of both: Substack as an amazing email social network, and MkDocs Material’s awesome look. So I’ve gone with using Substack as the core platform which I use to manage subscribers, and use it to post either math/code-free posts or a short teasers pointing to my main blog site on MkDocs Material when I need to show math/code

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

I've been migrating content to MKDocs (Material) over the last few months, so feel fairly qualified on this subject. It's somewhat limited in terms of navigation, but can probably handle 400-500 pages; you can see how navigation works in the link. Otherwise, it can handle most, if not all, the tasks you've listed.