From 56815b88ef5b14a689ff4b2c475077a070c4e7b1 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Wed, 18 Mar 2026 19:42:51 +0100 Subject: [PATCH 1/3] tools.md: HTML gens reorganized with tabs Some repetitions between tabs, but still shorter. Mention "general features" of HTML static site generators. --- content/tools.md | 170 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 124 insertions(+), 46 deletions(-) diff --git a/content/tools.md b/content/tools.md index 2a09d980..6fe616a1 100644 --- a/content/tools.md +++ b/content/tools.md @@ -39,7 +39,7 @@ For a closer look at this see the {ref}`writing-readme-files` episode. --- -## reStructuredText and Markdown +## Plain Text formats: reStructuredText and Markdown ```markdown # This is a section in Markdown This is a section in RST @@ -77,39 +77,138 @@ tables, links, ... tables, links, ... - Nice resource to learn Markdown: [Learn Markdown in 60 seconds](https://commonmark.org/help/) - [Pandoc](https://pandoc.org/) can convert between MD and RST (and many other formats). ---- -## HTML static site generators -There are many tools that can turn RST or Markdown into beautiful HTML pages: +--- -- [Sphinx](https://www.sphinx-doc.org) **← this is how this lesson material is built** - - Generate HTML/PDF/LaTeX from RST and Markdown. - - Basically all Python projects use Sphinx but **Sphinx is not limited to Python**. - - [Read the docs](https://readthedocs.org) - hosts public Sphinx documentation for free! - - Also hostable anywhere else, like Github pages. - - API documentation possible. +## HTML static site generators -- [Jekyll](https://jekyllrb.com) - - Generates HTML from Markdown. - - GitHub supports this without adding extra build steps. +There are many tools generate documentation +that can be +viewed locally, +or hosted on the web. + +Here are some HTML static site generators, relevant in our communities. +These tools offer some or all of these features: +- **API Reference generation**: source code is read, scan for docstrings and render them +- **Search**: they offer a "whole site" search feature (non trivial, when viewing only one page). + (if you can download ) +- **Validation**: check that the code snipped in the documentation + match the real behaviour of the code. +- **Continous checks**: regenerate automatically every time you save, so that you can catch errors early + +````{tabs} + ```{group-tab} Python + - [Sphinx](https://www.sphinx-doc.org) **this is how this lesson material is built** + - Generate HTML/PDF/LaTeX from RST and Markdown (MyST) + - Basically all Python projects use Sphinx but **Sphinx is not limited to Python**. + - [Read the docs](https://about.readthedocs.com) + hosts public Sphinx documentation for free! + - **API Reference generation**: via + [autodoc](https://sphinx-autodoc2.readthedocs.io/en/latest/) + or [autoapi](https://sphinx-autoapi.readthedocs.io/en/latest/) + - **Search:** + - limited, keyword-based client-side (Javascript that runs in browser) + - Full-text server-side on [Read the docs](https://about.readthedocs.com) + - **Validation**: via [doctest](https://docs.python.org/3/library/doctest.html) + + - [MkDocs](https://www.mkdocs.org/): A Markdown-first static site generator. + - **API Reference generation**: via + [mkdocstrings](https://mkdocstrings.github.io/) + - **Search:** search plugin for client-side (Javascript that runs in the browser - lunr.js) + + - [Doxygen](https://www.doxygen.nl/): + - **API Reference generation**: has also support for Python + + ``` + ```{group-tab} R + [pkgdown](https://pkgdown.r-lib.org/) + Long-Form Documentation for R is typically contained in [vignettes](https://r-pkgs.org/vignettes.html) + - **API Reference generation**: via + [roxygen2](https://roxygen2.r-lib.org/) and + Rdconv + - Uses RMarkdown and a LaTeX-like syntax + - **Search:** + - client-side (Javascript that runs in browser - fuse.js) + - also typically avaiable in RStudio + + ``` + ```{group-tab} C/C++ + - [Doxygen](https://www.doxygen.nl/) + - **API Reference generation** out of the box, generates static call graph + - Focus on Documentation directly in the source code + - MarkDown-like syntax, with its own flavour and [special commands](https://www.doxygen.nl/manual/commands.html) + - **Search**: + - limited keyword-based client-side + - full text search server-side + - [Sphinx](https://www.sphinx-doc.org) can be also used to generate documentation for C++ projects, using the XML output from Doxygen via [Breathe](https://breathe.readthedocs.io/en/latest/) + + ``` + + ```{group-tab} Fortran + - [Doxygen](https://www.doxygen.nl/): + - **API Reference generation** out of the box, generates static call graph (but has limited Fortran parsing capabilities) + - Focus on Documentation directly in the source code + - MarkDown-like syntax, with its own flavour and [special commands](https://www.doxygen.nl/manual/commands.html) + - **Search**: + - limited keyword-based client-side + - full text search server-side + + - [FORD](https://forddocs.readthedocs.io/en/stable/) + - Python-based + - **Search:** client-side (Javascript that runs in the browser - lunr.js) + + ``` + ```{group-tab} Julia + - [Documenter.jl](https://documenter.juliadocs.org/stable/) + - Using MarkDown (JuliaMarkdown flavour) + - Parses Julia code and in-code documentation/docstrings + - **Search**: client-side (but typically the whole site is loaded for search on every page) + - **Validation:** runs the code and checks + + ``` + + ```{group-tab} Rust + [RustDoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html) + - Uses MarkDown (CommonMark flavour) + - **Search**: client-side (Javascript that runs in the browser - elasticlunr.js) + - **Validation**: validates code examples when run with `--test` + + ``` + + ```{group-tab} Any + These are general-purpose static website generators + that match the philosophy of the other tools presented so far, + but might be better suited for blogging, reports or other kinds of publications: + + - [Hugo](https://gohugo.io) + - [Hexo](https://hexo.io) + - [Zola](https://www.getzola.org/) **<- this is what we use for our project website and workshop websites** + - [Jekyll](https://jekyllrb.com/), default for GitHub pages + + - [Franklin.jl](https://github.com/JuliaDocs/Franklin.jl): focuses on technical blogging for the Julia community + - [Quarto](https://quarto.org/) converts markdown to websites, pdfs, ebooks and many other things (dynamic notebook-based documents) + ``` +```` + +```{discussion} + +Do you know an awesome tool or feature that should be in this list? +Let us know! (Open a PR) -- [pkgdown](https://pkgdown.r-lib.org/) - - Popular in the R community +``` -- [MkDocs](https://www.mkdocs.org/) -- [GitBook](https://www.gitbook.com/) -- [Hugo](https://gohugo.io) -- [Hexo](https://hexo.io) -- [Zola](https://www.getzola.org/) **<- this is what we use for our project website and workshop websites** -- There are many more ... +## Hosting Documentation on the Web GitHub, GitLab, and Bitbucket make it possible to serve HTML pages: - [GitHub Pages](https://pages.github.com) - [Bitbucket Pages](https://pages.bitbucket.io/) - [GitLab Pages](https://pages.gitlab.io) +[Read The Docs](https://about.readthedocs.io) is also free to use for open source code, +and can be [connected](https://docs.readthedocs.com/platform/latest/reference/git-integration.htm) +to common software forges. + --- ## Wikis @@ -125,6 +224,9 @@ GitHub, GitLab, and Bitbucket make it possible to serve HTML pages: - Difficult to check out a specific old version - Typically needs to be hosted and maintained + + + --- ## LaTeX/PDF @@ -135,34 +237,10 @@ GitHub, GitLab, and Bitbucket make it possible to serve HTML pages: - PDF format is not ideal for copy-pasting of examples - Possible, but not trivial to automate rebuilding documentation after every Git push ---- - -## Doxygen -- Auto-generates API documentation -- Documented directly in the source code -- Popular in the C++ community -- Has support for C, Fortran, Python, Java, etc., - see [Doxygen Github Repo](https://github.com/doxygen/doxygen) -- Many keywords are understood by Doxygen: - [Doxygen special commands](https://www.doxygen.nl/manual/commands.html) -- Can be used to also generate higher-level ("human") documentation -- Can be deployed to GiHub/GitLab/Bitbucket Pages --- -## Other tools - -- Fortran - - [Fortran Documenter (FORD)](https://github.com/Fortran-FOSS-Programmers/ford) - -- Julia - - [Franklin](https://franklinjl.org/): static site generator - - [Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/) - -- [Quarto](https://quarto.org/) converts markdown to websites, pdfs, ebooks and many other things - ---- ```{keypoints} - Some popular solutions make reproducibility and maintenance of multiple code versions difficult. From c04a287790b0c2ba80c949ca261c080bd28b3185 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Thu, 19 Mar 2026 17:18:41 +0100 Subject: [PATCH 2/3] HTML gen comparison: minor fixes/tweaks --- content/tools.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/content/tools.md b/content/tools.md index 6fe616a1..fce8a5a8 100644 --- a/content/tools.md +++ b/content/tools.md @@ -99,7 +99,7 @@ These tools offer some or all of these features: ````{tabs} ```{group-tab} Python - - [Sphinx](https://www.sphinx-doc.org) **this is how this lesson material is built** + - [Sphinx](https://www.sphinx-doc.org) **← this is how this lesson material is built** - Generate HTML/PDF/LaTeX from RST and Markdown (MyST) - Basically all Python projects use Sphinx but **Sphinx is not limited to Python**. - [Read the docs](https://about.readthedocs.com) @@ -122,15 +122,16 @@ These tools offer some or all of these features: ``` ```{group-tab} R - [pkgdown](https://pkgdown.r-lib.org/) - Long-Form Documentation for R is typically contained in [vignettes](https://r-pkgs.org/vignettes.html) - - **API Reference generation**: via - [roxygen2](https://roxygen2.r-lib.org/) and - Rdconv - - Uses RMarkdown and a LaTeX-like syntax - - **Search:** - - client-side (Javascript that runs in browser - fuse.js) - - also typically avaiable in RStudio + - [pkgdown](https://pkgdown.r-lib.org/) + - **API Reference generation**: via + [roxygen2](https://roxygen2.r-lib.org/) and + Rdconv + - Uses RMarkdown and a LaTeX-like syntax + - **Search:** + - client-side (Javascript that runs in browser - fuse.js) + - also typically avaiable in RStudio + + Long-Form Documentation for R is typically contained in [vignettes](https://r-pkgs.org/vignettes.html). ``` ```{group-tab} C/C++ @@ -183,7 +184,7 @@ These tools offer some or all of these features: - [Hugo](https://gohugo.io) - [Hexo](https://hexo.io) - - [Zola](https://www.getzola.org/) **<- this is what we use for our project website and workshop websites** + - [Zola](https://www.getzola.org/) **← this is what we use for our project website and workshop websites** - [Jekyll](https://jekyllrb.com/), default for GitHub pages - [Franklin.jl](https://github.com/JuliaDocs/Franklin.jl): focuses on technical blogging for the Julia community From e97ceec52280915915e16441be848fc3a2a45c78 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Thu, 19 Mar 2026 17:29:34 +0100 Subject: [PATCH 3/3] tools: table with comparison to be discussed. The table tries to summarise, but too much summarisation might just result in ambiguous/debatable/wrong statements --- content/tools.md | 196 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 136 insertions(+), 60 deletions(-) diff --git a/content/tools.md b/content/tools.md index fce8a5a8..ac2b2d1a 100644 --- a/content/tools.md +++ b/content/tools.md @@ -11,7 +11,84 @@ --- -## In-code documentation +## Documentation Tools: comparison + +```{list-table} Comparison of the tools for documentation we have discussed so far +:widths: 20 10 10 10 10 10 10 15 +:header-rows: 1 +:stub-columns: 1 + +* - Type + - Convenient + - Easy + - Maintainabile + - Searchable + - Readable + - LLM-friendly + - Notes +* - in-code doc + - ✅✅ + - 🟨 + - ✅🟨 + - 🟨 + - ❌ + - ✅🟨 + - ❌for users +* - README + - ✅ + - ✅ + - ✅🟨 + - 🟨 + - ✅ + - ✅ + - typically enough +* - HTML Generators + - 🟨 + - ❌ + - ✅🟨 + - ✅ + - ❌ + - ✅✅ + - powerful +* - Wikis + - 🟨 + - ✅ + - ❌❌ + - ✅ + - ✅ + - ❌ + - ✅for non-programmers +* - Latex + - 🟨(?) + - ❌ + - ❌🟨 + - 🟨 + - ✅ (?) + - ❌ + - ✅Physics/Math, + ❌copy/paste +* - Jupyter + - 🟨 + - 🟨/❌ + - ✅✅ + - 🟨 (?) + - ✅ + - 🟨 + - ✅ validation tooling +``` + +What do we mean? +- **Convenience**: for programmers who live in code. +- **Easiness**: how easy is is to contribute and set up? +- **Maintainability** is good for those tools that can be version-controlled along with the code. + It is even better if it is easy to check automatically that the information is correct + (*does the output of a snippet of code match what is shown in the docs?*) +- **Searchability:** How easy is it to find the information we need? +- **Readability**: Can the documentation be rendered in a way that makes it easy to read? +- **LLM-friendliness**: how easy is to feed this documentation to an LLM? + + +### In-code documentation - Comments, function docstrings, ... - Advantages @@ -24,8 +101,7 @@ For a closer look at this see the {ref}`in-code-documentation` episode. --- - -## README files +### README files - Advantages - Versioned (goes with the code development) @@ -39,44 +115,31 @@ For a closer look at this see the {ref}`writing-readme-files` episode. --- -## Plain Text formats: reStructuredText and Markdown - -```markdown -# This is a section in Markdown This is a section in RST - ======================== - -## This is a subsection This is a subsection - -------------------- - -Nothing special needed for Nothing special needed for -a normal paragraph. a normal paragraph. +### Wikis - :: +- Popular solutions (but many others exist): + - [MediaWiki](https://www.mediawiki.org) + - [Dokuwiki](https://www.dokuwiki.org) +- Advantage + - Barrier to write and edit is low +- Disadvantages + - Typically disconnected from source code repository (**reproducibility**) + - Difficult to serve multiple versions + - Difficult to check out a specific old version + - Typically needs to be hosted and maintained - This is a code block This is a code block -**Bold** and *emphasized*. **Bold** and *emphasized*. -A list: A list: -- this is an item - this is an item -- another item - another item +--- -There is more: images, There is more: images, -tables, links, ... tables, links, ... -``` - -- Two of the most popular lightweight markup languages. -- reStructuredText (RST) has more features than Markdown but the choice is a matter of taste. -- There are (unfortunately) [many flavors of Markdown](https://github.com/jgm/CommonMark/wiki/Markdown-Flavors). -- Motivation to stick to a standard text-based format: **They make it easier to move the documentation to other tools - which also expect a standard format, as the project/organization grows**. -- We use [MyST](https://myst-parser.readthedocs.io/en/latest/) - flavored Markdown in the {ref}`sphinx` episode and the - {ref}`gh-pages` example. -- Nice resource to learn Markdown: [Learn Markdown in 60 seconds](https://commonmark.org/help/) -- [Pandoc](https://pandoc.org/) can convert between MD and RST (and many other formats). +### LaTeX/PDF +- Advantage + - Popular and familiar in the physics and mathematics community +- Disadvantages + - PDF format is not ideal for copy-pasting of examples + - Possible, but not trivial to automate rebuilding documentation after every Git push --- @@ -95,7 +158,7 @@ These tools offer some or all of these features: (if you can download ) - **Validation**: check that the code snipped in the documentation match the real behaviour of the code. -- **Continous checks**: regenerate automatically every time you save, so that you can catch errors early +- **Continuous checks**: regenerate automatically every time you save, so that you can catch errors early ````{tabs} ```{group-tab} Python @@ -129,7 +192,7 @@ These tools offer some or all of these features: - Uses RMarkdown and a LaTeX-like syntax - **Search:** - client-side (Javascript that runs in browser - fuse.js) - - also typically avaiable in RStudio + - also typically available in RStudio Long-Form Documentation for R is typically contained in [vignettes](https://r-pkgs.org/vignettes.html). @@ -192,12 +255,8 @@ These tools offer some or all of these features: ``` ```` -```{discussion} - -Do you know an awesome tool or feature that should be in this list? -Let us know! (Open a PR) +--- -``` ## Hosting Documentation on the Web @@ -210,37 +269,54 @@ GitHub, GitLab, and Bitbucket make it possible to serve HTML pages: and can be [connected](https://docs.readthedocs.com/platform/latest/reference/git-integration.htm) to common software forges. + + +```{discussion} + +Do you know an awesome tool or feature that should be in this list? +Let us know! (Open a PR) + +``` + --- -## Wikis +### Plain Text formats: reStructuredText and Markdown -- Popular solutions (but many others exist): - - [MediaWiki](https://www.mediawiki.org) - - [Dokuwiki](https://www.dokuwiki.org) -- Advantage - - Barrier to write and edit is low -- Disadvantages - - Typically disconnected from source code repository (**reproducibility**) - - Difficult to serve multiple versions - - Difficult to check out a specific old version - - Typically needs to be hosted and maintained +```markdown +# This is a section in Markdown This is a section in RST + ======================== +## This is a subsection This is a subsection + -------------------- +Nothing special needed for Nothing special needed for +a normal paragraph. a normal paragraph. + :: ---- + This is a code block This is a code block -## LaTeX/PDF -- Advantage - - Popular and familiar in the physics and mathematics community -- Disadvantages - - PDF format is not ideal for copy-pasting of examples - - Possible, but not trivial to automate rebuilding documentation after every Git push +**Bold** and *emphasized*. **Bold** and *emphasized*. +A list: A list: +- this is an item - this is an item +- another item - another item +There is more: images, There is more: images, +tables, links, ... tables, links, ... +``` ---- +- Two of the most popular lightweight markup languages. +- reStructuredText (RST) has more features than Markdown but the choice is a matter of taste. +- There are (unfortunately) [many flavors of Markdown](https://github.com/jgm/CommonMark/wiki/Markdown-Flavors). +- Motivation to stick to a standard text-based format: **They make it easier to move the documentation to other tools + which also expect a standard format, as the project/organization grows**. +- We use [MyST](https://myst-parser.readthedocs.io/en/latest/) + flavored Markdown in the {ref}`sphinx` episode and the + {ref}`gh-pages` example. +- Nice resource to learn Markdown: [Learn Markdown in 60 seconds](https://commonmark.org/help/) +- [Pandoc](https://pandoc.org/) can convert between MD and RST (and many other formats). ```{keypoints}