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.
-
Open the
docsfolder in the editor and change a page, for exampleteaching/egm703/practicals/week3.rst. Screenshots go indocs/img/egm703/week3/. -
Build:
make html, which runssphinx-buildand writes the pages into the second checkout (../../iamdonovan-sphinx-docs, thegh-pagesbranch). Open the built page in a browser to check it. -
Commit the source on
mainand push. -
In the second checkout, commit the rebuilt pages with the same message and push. GitHub Pages serves them within a minute.
-
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.
-
Open the project in RStudio or VS Code (both have Quarto extensions). Each chapter is a
.qmdfile listed in_quarto.yml. -
Run
quarto preview. A local server opens the book in the browser and re-renders the chapter each time it is saved. -
Commit and push to
main. The workflow in.github/workflowsrenders the whole book on a clean machine and publishes it to GitHub Pages; nothing built is committed by hand. Code results already in_freezeare reused. -
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).
-
Write MyST Markdown (
.md) or notebooks (.ipynb) in VS Code or JupyterLab; the table of contents is inmyst.yml. -
Run
jupyter book start(ormyst start): a live local server that updates as files are saved. -
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).
-
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. -
Commit and push (or open a pull request so co-authors can review the change line by line).
-
The workflow
manubot.yamlbuilds 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 withlatexdiff 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¶
-
Open the document: from any page’s Admin bar (Studio, VS Code or browser), or
python -m research_helpers.stack studio. -
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.
-
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 tomain, and the site’s workflow deploys them. -
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.