Skip to content

remove tool comparison table (needs more review) #334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
frankier merged 1 commit into from
Mar 23, 2026
Merged

remove tool comparison table (needs more review) #334

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 58 additions & 135 deletions content/tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,84 +11,7 @@

---

## 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
## In-code documentation

- Comments, function docstrings, ...
- Advantages
Expand All @@ -101,7 +24,8 @@ What do we mean?
For a closer look at this see the {ref}`in-code-documentation` episode.

---
### README files

## README files

- Advantages
- Versioned (goes with the code development)
Expand All @@ -115,31 +39,44 @@ For a closer look at this see the {ref}`writing-readme-files` episode.

---

### 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).



---
Expand Down Expand Up @@ -255,8 +192,12 @@ 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

Expand All @@ -269,55 +210,37 @@ 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)

```

---

### Plain Text formats: reStructuredText and Markdown
## Wikis

```markdown
# This is a section in Markdown This is a section in RST
========================
- 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 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

**Bold** and *emphasized*. **Bold** and *emphasized*.
- 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

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}
Expand Down
Loading