Current status (as at March 2022) of Python-based tools for generating scientific reports from markdown+code.
Pweave (https://github.com/mpastell/Pweave)
- Unmaintained. Only supports Python >= 3.4 and <= 3.6, all of which are past end of life; and it's incompatible with current versions of some of its dependencies (e.g. jupyter-client)
Stitch (https://github.com/pystitch/stitch)
- Seems unmaintained. Last significant commit in Jan 2018, last closed issue in Dec 2018. Haven't checked to see if there are current compatibility issues.
- Recommends [
knitpy] as a more mature alternative, but that's inactive. - Has an active fork by @kiwi0fruit,
knitty
Knitpy (https://github.com/jankatins/knitpy)
- Inactive
- Possibly active - last commit Oct 2020, last closed issue Oct 2020.
- BUT one of its dependencies, py-pandoc (https://github.com/kiwi0fruit/py-pandoc) has been
failing to install using
pipsince July 2021, and this hasn't been fixed - Fails on Python 3.6 (but perhaps fair enough since 3.6 is past EOL) and Python 3.8 using
pip. - Bug reported here: kiwi0fruit/knitty#25
As a package, knitty seems to engage in fairly anti-social behaviour: it overwrites any pandoc executable a user may already have installed at ~/.local/bin/pandoc with a downloaded executable (quite probably of lower version) of its own choosing.
Its py-pandoc dependency (also by @kiwi0fruit) is responsible for this downloading, and makes some quite eccentric1 design choices, itself. Its setup.py file abuses pip for use as a general file-downloader-and-hashsum-checking-tool - it runs the command python3 -m pip download --require-hashes --no-clean -r /path/torequirements.txt on a requirements.txt file with contents:
https://anaconda.org/conda-forge/pandoc/2.9.2.1/download/linux-64/pandoc-2.9.2.1-0.tar.bz2 --hash=sha256:a63d9987414f3109265955855b5aba79bb8279321f119ff760342d1ee1d3e814
in order to download a known version of Pandoc, and then parses the output because it expects Pip to throw a particular error message which pandoc-2.9.2.1-0.tar.bz2 turns out not to be a Python package, and if that error message doesn't contain the words it expects, it then has the nerve to throw an exception complaining that "pip download behaviour changed". Why on earth would you not only rely on a tool doing something it was never intended to do, but then further rely on its error messages containing particular words in the error message? Words fail me. I can't see how any sane or half-way competent programmer would ever think this is a sensible thing to do.
(For reference: the not-insane thing to do here would be to use a general purpose HTTP client library like
urllib or requests, and then check the hashes using hashlib. I'm only a casual Python programmer,
and even I know that much.)
-
jupinx: uses Sphinx.
Another list of literate report-writing tools (but now out of date):
https://bl.ocks.org/mrtns/da998d5fde666d6da26807e1f246246e
Footnotes
-
A euphemism. I mean "utterly incompetent and insane". ↩