Skip to content

Commit 56815b8

Browse files
author
Michele Mesiti
committed
tools.md: HTML gens reorganized with tabs
Some repetitions between tabs, but still shorter. Mention "general features" of HTML static site generators.
1 parent 988cb9c commit 56815b8

1 file changed

Lines changed: 124 additions & 46 deletions

File tree

‎content/tools.md‎

Lines changed: 124 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ For a closer look at this see the {ref}`writing-readme-files` episode.
3939

4040
---
4141

42-
## reStructuredText and Markdown
42+
## Plain Text formats: reStructuredText and Markdown
4343

4444
```markdown
4545
# This is a section in Markdown This is a section in RST
@@ -77,39 +77,138 @@ tables, links, ... tables, links, ...
7777
- Nice resource to learn Markdown: [Learn Markdown in 60 seconds](https://commonmark.org/help/)
7878
- [Pandoc](https://pandoc.org/) can convert between MD and RST (and many other formats).
7979

80-
---
8180

82-
## HTML static site generators
8381

84-
There are many tools that can turn RST or Markdown into beautiful HTML pages:
82+
---
8583

86-
- [Sphinx](https://www.sphinx-doc.org) **← this is how this lesson material is built**
87-
- Generate HTML/PDF/LaTeX from RST and Markdown.
88-
- Basically all Python projects use Sphinx but **Sphinx is not limited to Python**.
89-
- [Read the docs](https://readthedocs.org)
90-
hosts public Sphinx documentation for free!
91-
- Also hostable anywhere else, like Github pages.
92-
- API documentation possible.
84+
## HTML static site generators
9385

94-
- [Jekyll](https://jekyllrb.com)
95-
- Generates HTML from Markdown.
96-
- GitHub supports this without adding extra build steps.
86+
There are many tools generate documentation
87+
that can be
88+
viewed locally,
89+
or hosted on the web.
90+
91+
Here are some HTML static site generators, relevant in our communities.
92+
These tools offer some or all of these features:
93+
- **API Reference generation**: source code is read, scan for docstrings and render them
94+
- **Search**: they offer a "whole site" search feature (non trivial, when viewing only one page).
95+
(if you can download )
96+
- **Validation**: check that the code snipped in the documentation
97+
match the real behaviour of the code.
98+
- **Continous checks**: regenerate automatically every time you save, so that you can catch errors early
99+
100+
````{tabs}
101+
```{group-tab} Python
102+
- [Sphinx](https://www.sphinx-doc.org) **this is how this lesson material is built**
103+
- Generate HTML/PDF/LaTeX from RST and Markdown (MyST)
104+
- Basically all Python projects use Sphinx but **Sphinx is not limited to Python**.
105+
- [Read the docs](https://about.readthedocs.com)
106+
hosts public Sphinx documentation for free!
107+
- **API Reference generation**: via
108+
[autodoc](https://sphinx-autodoc2.readthedocs.io/en/latest/)
109+
or [autoapi](https://sphinx-autoapi.readthedocs.io/en/latest/)
110+
- **Search:**
111+
- limited, keyword-based client-side (Javascript that runs in browser)
112+
- Full-text server-side on [Read the docs](https://about.readthedocs.com)
113+
- **Validation**: via [doctest](https://docs.python.org/3/library/doctest.html)
114+
115+
- [MkDocs](https://www.mkdocs.org/): A Markdown-first static site generator.
116+
- **API Reference generation**: via
117+
[mkdocstrings](https://mkdocstrings.github.io/)
118+
- **Search:** search plugin for client-side (Javascript that runs in the browser - lunr.js)
119+
120+
- [Doxygen](https://www.doxygen.nl/):
121+
- **API Reference generation**: has also support for Python
122+
123+
```
124+
```{group-tab} R
125+
[pkgdown](https://pkgdown.r-lib.org/)
126+
Long-Form Documentation for R is typically contained in [vignettes](https://r-pkgs.org/vignettes.html)
127+
- **API Reference generation**: via
128+
[roxygen2](https://roxygen2.r-lib.org/) and
129+
Rdconv
130+
- Uses RMarkdown and a LaTeX-like syntax
131+
- **Search:**
132+
- client-side (Javascript that runs in browser - fuse.js)
133+
- also typically avaiable in RStudio
134+
135+
```
136+
```{group-tab} C/C++
137+
- [Doxygen](https://www.doxygen.nl/)
138+
- **API Reference generation** out of the box, generates static call graph
139+
- Focus on Documentation directly in the source code
140+
- MarkDown-like syntax, with its own flavour and [special commands](https://www.doxygen.nl/manual/commands.html)
141+
- **Search**:
142+
- limited keyword-based client-side
143+
- full text search server-side
144+
- [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/)
145+
146+
```
147+
148+
```{group-tab} Fortran
149+
- [Doxygen](https://www.doxygen.nl/):
150+
- **API Reference generation** out of the box, generates static call graph (but has limited Fortran parsing capabilities)
151+
- Focus on Documentation directly in the source code
152+
- MarkDown-like syntax, with its own flavour and [special commands](https://www.doxygen.nl/manual/commands.html)
153+
- **Search**:
154+
- limited keyword-based client-side
155+
- full text search server-side
156+
157+
- [FORD](https://forddocs.readthedocs.io/en/stable/)
158+
- Python-based
159+
- **Search:** client-side (Javascript that runs in the browser - lunr.js)
160+
161+
```
162+
```{group-tab} Julia
163+
- [Documenter.jl](https://documenter.juliadocs.org/stable/)
164+
- Using MarkDown (JuliaMarkdown flavour)
165+
- Parses Julia code and in-code documentation/docstrings
166+
- **Search**: client-side (but typically the whole site is loaded for search on every page)
167+
- **Validation:** runs the code and checks
168+
169+
```
170+
171+
```{group-tab} Rust
172+
[RustDoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html)
173+
- Uses MarkDown (CommonMark flavour)
174+
- **Search**: client-side (Javascript that runs in the browser - elasticlunr.js)
175+
- **Validation**: validates code examples when run with `--test`
176+
177+
```
178+
179+
```{group-tab} Any
180+
These are general-purpose static website generators
181+
that match the philosophy of the other tools presented so far,
182+
but might be better suited for blogging, reports or other kinds of publications:
183+
184+
- [Hugo](https://gohugo.io)
185+
- [Hexo](https://hexo.io)
186+
- [Zola](https://www.getzola.org/) **<- this is what we use for our project website and workshop websites**
187+
- [Jekyll](https://jekyllrb.com/), default for GitHub pages
188+
189+
- [Franklin.jl](https://github.com/JuliaDocs/Franklin.jl): focuses on technical blogging for the Julia community
190+
- [Quarto](https://quarto.org/) converts markdown to websites, pdfs, ebooks and many other things (dynamic notebook-based documents)
191+
```
192+
````
193+
194+
```{discussion}
195+
196+
Do you know an awesome tool or feature that should be in this list?
197+
Let us know! (Open a PR)
97198
98-
- [pkgdown](https://pkgdown.r-lib.org/)
99-
- Popular in the R community
199+
```
100200

101-
- [MkDocs](https://www.mkdocs.org/)
102-
- [GitBook](https://www.gitbook.com/)
103-
- [Hugo](https://gohugo.io)
104-
- [Hexo](https://hexo.io)
105-
- [Zola](https://www.getzola.org/) **<- this is what we use for our project website and workshop websites**
106-
- There are many more ...
201+
## Hosting Documentation on the Web
107202

108203
GitHub, GitLab, and Bitbucket make it possible to serve HTML pages:
109204
- [GitHub Pages](https://pages.github.com)
110205
- [Bitbucket Pages](https://pages.bitbucket.io/)
111206
- [GitLab Pages](https://pages.gitlab.io)
112207

208+
[Read The Docs](https://about.readthedocs.io) is also free to use for open source code,
209+
and can be [connected](https://docs.readthedocs.com/platform/latest/reference/git-integration.htm)
210+
to common software forges.
211+
113212
---
114213

115214
## Wikis
@@ -125,6 +224,9 @@ GitHub, GitLab, and Bitbucket make it possible to serve HTML pages:
125224
- Difficult to check out a specific old version
126225
- Typically needs to be hosted and maintained
127226

227+
228+
229+
128230
---
129231

130232
## LaTeX/PDF
@@ -135,34 +237,10 @@ GitHub, GitLab, and Bitbucket make it possible to serve HTML pages:
135237
- PDF format is not ideal for copy-pasting of examples
136238
- Possible, but not trivial to automate rebuilding documentation after every Git push
137239

138-
---
139-
140-
## Doxygen
141240

142-
- Auto-generates API documentation
143-
- Documented directly in the source code
144-
- Popular in the C++ community
145-
- Has support for C, Fortran, Python, Java, etc.,
146-
see [Doxygen Github Repo](https://github.com/doxygen/doxygen)
147-
- Many keywords are understood by Doxygen:
148-
[Doxygen special commands](https://www.doxygen.nl/manual/commands.html)
149-
- Can be used to also generate higher-level ("human") documentation
150-
- Can be deployed to GiHub/GitLab/Bitbucket Pages
151241

152242
---
153243

154-
## Other tools
155-
156-
- Fortran
157-
- [Fortran Documenter (FORD)](https://github.com/Fortran-FOSS-Programmers/ford)
158-
159-
- Julia
160-
- [Franklin](https://franklinjl.org/): static site generator
161-
- [Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/)
162-
163-
- [Quarto](https://quarto.org/) converts markdown to websites, pdfs, ebooks and many other things
164-
165-
---
166244

167245
```{keypoints}
168246
- Some popular solutions make reproducibility and maintenance of multiple code versions difficult.

0 commit comments

Comments
 (0)