diff --git a/content/tools.md b/content/tools.md index 15e101e..25c75c8 100644 --- a/content/tools.md +++ b/content/tools.md @@ -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 @@ -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) @@ -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). + --- @@ -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 @@ -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}