Skip to content
Ahmad Ammar

4. Whole workflows, step by step

The previous chapters compared tools. This one follows a working day: where a person opens the text, how they see the result while writing, what they type to publish, and what they do the next time something needs changing. Where a step is read from a public repository it says so; where it comes from a tool’s own documentation, that is named instead.

4.1 A Sphinx teaching site (Chapter 2)

Read from the repository: the .gitignore was generated for PyCharm, so the source is most likely edited in a JetBrains IDE; the built site lives in a second checkout beside the source; and each commit on the published branch repeats the message of the source commit.

  1. Open the docs folder in the editor and change a page, for example teaching/egm703/practicals/week3.rst. Screenshots go in docs/img/egm703/week3/.

  2. Build: make html, which runs sphinx-build and writes the pages into the second checkout (../../iamdonovan-sphinx-docs, the gh-pages branch). Open the built page in a browser to check it.

  3. Commit the source on main and push.

  4. In the second checkout, commit the rebuilt pages with the same message and push. GitHub Pages serves them within a minute.

  5. Next time: the same four steps. A reader who spots a problem can use the issue button on the page; the edit button takes the author straight to the source file on GitHub.

Two commits per change, both made by hand, is the cost of not having CI; the benefit is that nothing but Sphinx needs to be installed anywhere.

4.2 A Quarto book

From the Quarto documentation (Posit 2026) and the R for Data Science repository.

  1. Open the project in RStudio or VS Code (both have Quarto extensions). Each chapter is a .qmd file listed in _quarto.yml.

  2. Run quarto preview. A local server opens the book in the browser and re-renders the chapter each time it is saved.

  3. Commit and push to main. The workflow in .github/workflows renders the whole book on a clean machine and publishes it to GitHub Pages; nothing built is committed by hand. Code results already in _freeze are reused.

  4. For a larger change: a branch and a pull request. In Geocomputation with Python, that pull request is built into a preview site before it is merged.

4.3 A Jupyter Book or MyST project

From the Jupyter Book and MyST documentation (Executable Books 2026).

  1. Write MyST Markdown (.md) or notebooks (.ipynb) in VS Code or JupyterLab; the table of contents is in myst.yml.

  2. Run jupyter book start (or myst start): a live local server that updates as files are saved.

  3. Push; CI builds the HTML (and, if configured, a PDF through LaTeX or Typst) and deploys. In The Turing Way, every pull request also runs link, alt-text and file-size checks and gets a Netlify preview.

4.4 A Manubot manuscript

From the Rootstock template (Himmelstein et al. 2019).

  1. Edit the Markdown files in content/, in any editor or directly in GitHub’s web editor. Cite by identifier, for example @doi:10.1371/journal.pcbi.1007128.

  2. Commit and push (or open a pull request so co-authors can review the change line by line).

  3. The workflow manubot.yaml builds HTML and PDF on GitHub and publishes them; each build keeps its own permanent address, so earlier versions can still be cited.

Writing happens entirely in git: review comments, suggested edits and authorship all come from GitHub.

4.5 A LaTeX paper or thesis

The most common setups among people who write LaTeX directly:

  • VS Code with LaTeX Workshop. Saving the file runs latexmk, the PDF sits in a tab beside the source, and SyncTeX links the two: Ctrl+click in the PDF jumps to the source line, and a command jumps the other way. The project is a git repository; the author commits and pushes when a section is done. Changes for co-authors or reviewers are shown with latexdiff old.tex new.tex > diff.tex.

  • Overleaf. The same edit-and-preview loop in the browser, with comments, tracked changes and a rich-text view for co-authors who do not write LaTeX. Git sync is on paid plans.

  • TeXstudio or TeXmaker. Desktop editors with a built-in PDF viewer and SyncTeX.

In each case the output is a PDF. Web pages, when wanted, come from a separate tool, which is the gap our stack fills.

4.6 Our stack

  1. Open the document: from any page’s Admin bar (Studio, VS Code or browser), or python -m research_helpers.stack studio.

  2. Write in the LaTeX or in the rendered preview; Studio re-renders as you type. For the exact PDF, Ctrl+Shift+B in VS Code.

  3. Publish: Save and publish in Studio, or python build_guides.py <guide> then commit and push. The build makes the PDF and the web pages together; both, with the source, are committed to main, and the site’s workflow deploys them.

  4. Next time: the same, from the page you want to change.

4.7 Practices nearly everyone shares

  • A live preview while writing: quarto preview, jupyter book start, sphinx-autobuild, LaTeX Workshop on save.

  • Built files are never edited. Changes go into the source and the site is rebuilt.

  • Built files kept out of the source history, either on a separate branch (the Sphinx site) or produced fresh by CI (Quarto, MyST, Manubot). We commit built pages beside the sources, which makes our history larger and our diffs noisier; building in CI would remove that.

  • Small commits with plain messages for routine fixes, straight to main.

  • A branch and a pull request for larger changes or other people’s contributions, ideally with a preview build to read before merging.

  • A written environment (environment.yml, DESCRIPTION, a dev container) so the build is the same on every machine.