If you were writing a thing that had chapters but also lots of links and code samples and equations, wanted to make sure it was updatable via git/github, and generated a static site with the option to render to text, what would you use?
@vicki I would probably spend way too much time rigging up a fragile latex pipeline that rendered both html and txt in GitHub Actions custom GitHub Pages deployment... https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#creating-a-custom-github-actions-workflow-to-publish-your-site . TBH I've never tried this though.
@vicki I've done a few projects now where the bulk of my writing is in a markdown file, and then I write a script to fill in the gaps, often by converting code blocks into diagrams. I publish through GitHub pages, as well as a PDF version.
If custom code isn't a good fit, I'd look at pandoc.
Here's the current project I'm working on with this style: https://github.com/donkirkby/chess-kit/blob/main/publish_rules.py
@vicki something in the myst / jupyter book space, but that's just because I follow @choldgraf and it looks neat
@vicki I would probably do latex as the source and convert it to another format. There are some pretty good latex to html renderers these days. I also recently heard about https://github.com/StevenClontz/pretext
@vicki I think Bookdown is pretty nice! There are already a lot of github workflows and templates available for it too. https://github.com/rstudio/bookdown
@vicki You may hear of GitBook, but walk right past it, since it’s an increasingly enshittifying service’s loss leader, but there’s a RIIR version of it that is used in the wider Rust world and works great: https://rust-lang.github.io/mdBook/
@vicki Jupyter Book is nice for this. You can easily render to HTML and LaTeX/pdf. It is easy to set up GitHub actions to do the compiling and pushing to GitHub pages. Shameless plug: you can also add interactive quizzes with Jupyter Quiz. See https://fdsp.net for an example
@vicki I would go for https://quarto.org/ by @Posit. Many books are written that way including https://wesmckinney.com/book/
@vicki I use Sphinx with the nbsphinx extension for my tutorials. This allows me to check links, execute code and also render mathematical formulae. And here are some tips for managing Jupyter notebooks in Git: https://www.python4data.science/en/latest/productive/git/advanced/jupyter-notebooks.html
@vicki definitely give quarto a try. We use it for our internal documentation website. Some images are created at build time from code and data (and tracked via git). It supports many output formats. Great experience working with it.
@vicki (forgot to add this) https://duckdb.hrbrmstr.app/ is the most recent Quarto book thing I've done (no equations tho).
@hrbrmstr @vicki I had my first proper play with duck db today and a query that takes ~20s to load parquet files and then summarise with data.table, when run as a summary query in duck db took no longer to run than just the data.table summary. No time waiting for data to load. Also used a fraction of the memory that loading data would. 🤯 so good!
@bearloga @vicki Now that I'm back to a computer, if you're interested in seeing some of my examples, this was built in JupyterBook: https://cs533.ekstrandom.net/f22/
And this is built in Quarto: https://bookdata.piret.info/
For future things I am most likely to use Quarto unless there is a specific benefit to using a Sphinx-based platform (e.g. incorporating Python API documentation).
