diff --git a/content/tools.md b/content/tools.md index 2a09d98..506284a 100644 --- a/content/tools.md +++ b/content/tools.md @@ -11,35 +11,236 @@ --- -## In-code documentation -- Comments, function docstrings, ... -- Advantages - - Good for programmers - - Version controlled alongside code - - Can be used to auto-generate documentation for functions/classes -- Disadvantage - - Probably not enough for users of the code +## 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? -For a closer look at this see the {ref}`in-code-documentation` episode. --- -## README files -- Advantages - - Versioned (goes with the code development) - - It is often good enough to have a `README.md` or `README.rst` along with your code/script -- If you use README files, use either - [RST](https://docutils.sourceforge.net/rst.html) or - [Markdown](https://commonmark.org/help/) -- A great guide to README files: [MakeaREADME](https://www.makeareadme.com/) +## HTML static site generators + +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. +- **Continuous 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 + (with a vast system of plugins developed independently). + - **API Reference generation**: via + [mkdocstrings](https://mkdocstrings.github.io/) + - **Search:** search plugin for client-side (Javascript that runs in the browser - lunr.js) + Project now (as of 2026) not maintained [^mkdocsdrama] + + [^mkdocsdrama]: After somewhat dramatic events (2026), + MkDocs 1.x is now superseded by [Zensical](https://zensical.org/), + which tries to keep compatibility wiht MkDocs 1.x. + (MkDocs 2.0 is also being developed + but projects and plugins based on 1.x + will break). + + + + - [Doxygen](https://www.doxygen.nl/): + - **API Reference generation**: has also support for Python + + ``` + ```{group-tab} R + - [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 available in RStudio + + Long-Form Documentation for R is typically contained in [vignettes](https://r-pkgs.org/vignettes.html). + + ``` + ```{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) + ``` +```` + +--- + + +## 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. + + + +```{discussion} -For a closer look at this see the {ref}`writing-readme-files` episode. +Do you know an awesome tool or feature that should be in this list? +Let us know! (Open a PR) + +``` --- -## reStructuredText and Markdown +### Plain Text formats: reStructuredText and Markdown ```markdown # This is a section in Markdown This is a section in RST @@ -77,93 +278,11 @@ 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. - -- [Jekyll](https://jekyllrb.com) - - Generates HTML from Markdown. - - GitHub supports this without adding extra build steps. - -- [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 ... - -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) - ---- - -## 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 - ---- - -## 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 - ---- - -## 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} +- READMEs are typically a good starting point - Some popular solutions make reproducibility and maintenance of multiple code versions difficult. +- The landscape of tools is very diversified and every community has their own favourite. +- The basic functionality of all Static site generators is very similar, + but specific aspects (API ref generation, search, validation) differ. ```