From bff94dd2015f8a77ccc16f225391efcfa6602f5d Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Sun, 24 Mar 2024 09:17:26 +0000 Subject: [PATCH 1/8] Update doc builder recommendations. Fixes #187. Relates to #16, #318, and #319. See discussion in #16. Depends on #319. --- docs/pages/docs.md | 62 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 12 deletions(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index d3ac23d7..e567d166 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -5,20 +5,58 @@ layout: default # Documentation -## Doc building - -| Name | Short description | 🚦 | -| ----------------------------------------------- | --------------------------------------------------------------- | :-: | -| [sphinx](https://www.sphinx-doc.org/en/master/) | Generates documentation from reStructuredText or Markdown files | 🟒 | -| [gitbook](https://www.gitbook.com/) | General documentation builder; integrates with GitHub | 🟠 | -| [mkdocs](https://www.mkdocs.org/) | Generates documentation from Markdown files | 🟠 | -| [pdoc](https://pdoc.dev/) | Auto-generates API documentation from docstrings | 🟠 | - -
- 🟒 explanation -Sphinx is the de-facto standard that is widely used. It is well tested, reliable and very customisable. +With Python, as with many other languages, it's very common to automatically +create a web page with documentation built from [docstrings] in your package's +API. For your package to be easily reusable we recommend you build documentation +pages and host them somewhere. + +If you're using GitHub, the simplest is to host your docs on [GitHub pages]. +[Here's how we've set this up][template-docs-dot-yaml] for [our template]. + + + +[docstrings]: https://peps.python.org/pep-0257/#what-is-a-docstring +[GitHub pages]: https://docs.github.com/en/pages +[our template]: https://github.com/UCL-ARC/python-tooling?tab=readme-ov-file#using-this-template +[template-docs-dot-yaml]: https://github.com/UCL-ARC/python-tooling/blob/main/%7B%7Bcookiecutter.project_slug%7D%7D/.github/workflows/docs.yml + +## Documentation build tools + +| Name | Short description | 🚦 | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: | +| [MkDocs] | Generates documentation from Markdown files, with a plugin to generate API documentation. A good plugin ecosystem and balance of usability and customisability. | 🟒 | +| [Sphinx] | Generates documentation from reStructuredText or Markdown files, long been the de-facto standard and very widely used. Mature plugin ecosystem. | 🟠 | +| [gitbook] | General documentation builder; integrates with GitHub. | 🟠 | +| [pdoc] | Auto-generates API documentation from docstrings, beginner friendly but with less of a plugin ecosystem than others. | 🟠 | + +
+More details about Sphinx + +We marginally recommend [MkDocs] over [Sphinx] due to it's ease of use, +preference for markdown, and slightly better support of our preferred docstring +style. + +However the [Sphinx] tool has long been the de-facto standard, it is widely +used, customisable, and well tested. If you need a [Sphinx +extension](#sphinx-extensions) that does not have an equivalent [MkDocs +plugin](https://github.com/mkdocs/catalog), or if you are part of a community +that heavily uses [Sphinx] then, as with all tools, we recommend you use that +instead. + +### See also + +- Our internal discussions about which to recommend ([#16](https://github.com/UCL-ARC/python-tooling/issues/16) and [#187](https://github.com/UCL-ARC/python-tooling/issues/187)). +- [An interesting related discussion](https://github.com/encode/httpx/discussions/1220). +
+ + +[MkDocs]: https://www.mkdocs.org/ +[Sphinx]: https://www.sphinx-doc.org/en/master/ +[gitbook]: https://www.gitbook.com/ +[pdoc]: https://pdoc.dev/ + ## Sphinx extensions | Name | Short description | 🚦 | From 992595277a1469da039ff8e05c08552b37a844b3 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 11:01:06 +0000 Subject: [PATCH 2/8] Suggestions from code review. Co-authored-by: Matt Graham Co-authored-by: David Stansby --- docs/pages/docs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index e567d166..d84501f1 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -7,7 +7,7 @@ layout: default With Python, as with many other languages, it's very common to automatically create a web page with documentation built from [docstrings] in your package's -API. For your package to be easily reusable we recommend you build documentation +_application programming interface_ (API). For your package to be easily reusable we recommend you build documentation pages and host them somewhere. If you're using GitHub, the simplest is to host your docs on [GitHub pages]. @@ -33,14 +33,14 @@ If you're using GitHub, the simplest is to host your docs on [GitHub pages]. More details about Sphinx We marginally recommend [MkDocs] over [Sphinx] due to it's ease of use, -preference for markdown, and slightly better support of our preferred docstring +preference for Markdown, and slightly better support of our preferred docstring style. -However the [Sphinx] tool has long been the de-facto standard, it is widely +However the [Sphinx] tool has long been the de-facto standard in the scientific Python ecosystem. It is widely used, customisable, and well tested. If you need a [Sphinx extension](#sphinx-extensions) that does not have an equivalent [MkDocs plugin](https://github.com/mkdocs/catalog), or if you are part of a community -that heavily uses [Sphinx] then, as with all tools, we recommend you use that +that heavily uses [Sphinx] then we recommend you use that instead. ### See also From 1a294420b8425e712178f32646f6b334cefbff78 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 11:03:22 +0000 Subject: [PATCH 3/8] GitHub pages may not be the simplest. Co-authored-by: David Stansby --- docs/pages/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index d84501f1..9cb790b6 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -10,7 +10,7 @@ create a web page with documentation built from [docstrings] in your package's _application programming interface_ (API). For your package to be easily reusable we recommend you build documentation pages and host them somewhere. -If you're using GitHub, the simplest is to host your docs on [GitHub pages]. +If you're using GitHub, one option is to host your docs on [GitHub pages]. [Here's how we've set this up][template-docs-dot-yaml] for [our template]. From c97ca4edcde8990a6fb35cb104201046d87ad480 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 11:51:08 +0000 Subject: [PATCH 4/8] Other types of docs than API. Co-authored-by: David Stansby --- docs/pages/docs.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index 9cb790b6..19a1e39b 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -6,9 +6,12 @@ layout: default # Documentation With Python, as with many other languages, it's very common to automatically -create a web page with documentation built from [docstrings] in your package's -_application programming interface_ (API). For your package to be easily reusable we recommend you build documentation -pages and host them somewhere. +create a web page with documentation. This can include reference for the API +taken from your package's [docstrings], tutorials, examples, and more in depth +explanation about how the package works. For an in-depth discussion of the +different components of good documentation, see the [DiÑtaxis +framework](https://diataxis.fr/). For your package to be easily reusable we +recommend you build documentation pages and host them somewhere. If you're using GitHub, one option is to host your docs on [GitHub pages]. [Here's how we've set this up][template-docs-dot-yaml] for [our template]. From 26c1e5bfd9eddc950bacdc3a2024d27582b2deb2 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 12:01:11 +0000 Subject: [PATCH 5/8] Add table for MkDocs plugins. --- docs/pages/docs.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index 19a1e39b..7f8dc483 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -60,9 +60,15 @@ instead. [gitbook]: https://www.gitbook.com/ [pdoc]: https://pdoc.dev/ +## MkDocs plugins + +| name | short description | 🚦 | +| ------------------------------------------------------------- | -------------------------------------------- | :-: | +| [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates api reference pages. | 🟒 | + ## Sphinx extensions -| Name | Short description | 🚦 | -| -------------------------------------------------------------------- | --------------------------------------------------------------- | :-: | -| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an HTML gallery of examples from a set of Python scripts | 🟒 | -| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates API reference pages. | 🟒 | +| name | short description | 🚦 | +| -------------------------------------------------------------------- | ---------------------------------------------------------------- | :-: | +| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an html gallery of examples from a set of python scripts. | 🟒 | +| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates api reference pages. | 🟒 | From bcab7cc797cc9ca28f6a371867325cd3c437cd34 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 12:02:38 +0000 Subject: [PATCH 6/8] Reword until we've decided our recommended docstring style. --- docs/pages/docs.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index 7f8dc483..023dd8dd 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -36,8 +36,7 @@ If you're using GitHub, one option is to host your docs on [GitHub pages]. More details about Sphinx We marginally recommend [MkDocs] over [Sphinx] due to it's ease of use, -preference for Markdown, and slightly better support of our preferred docstring -style. +preference for Markdown, and more support for a variety of docstring styles. However the [Sphinx] tool has long been the de-facto standard in the scientific Python ecosystem. It is widely used, customisable, and well tested. If you need a [Sphinx From 6ffb2f54a71b3ae46991d21e9bbb38d319c19105 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 15:49:47 +0000 Subject: [PATCH 7/8] api -> API Co-authored-by: Matt Graham --- docs/pages/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index 023dd8dd..d40a518c 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -63,7 +63,7 @@ instead. | name | short description | 🚦 | | ------------------------------------------------------------- | -------------------------------------------- | :-: | -| [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates api reference pages. | 🟒 | +| [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates API reference pages. | 🟒 | ## Sphinx extensions From b75137df41f3c1ddccc66461e61ddf7727791d21 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 25 Mar 2024 15:58:11 +0000 Subject: [PATCH 8/8] Revert lowercase barf. Co-authored-by: Matt Graham --- docs/pages/docs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/docs.md b/docs/pages/docs.md index d40a518c..5a9467f7 100644 --- a/docs/pages/docs.md +++ b/docs/pages/docs.md @@ -61,13 +61,13 @@ instead. ## MkDocs plugins -| name | short description | 🚦 | +| Name | Short description | 🚦 | | ------------------------------------------------------------- | -------------------------------------------- | :-: | | [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates API reference pages. | 🟒 | ## Sphinx extensions -| name | short description | 🚦 | +| Name | Short description | 🚦 | | -------------------------------------------------------------------- | ---------------------------------------------------------------- | :-: | -| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an html gallery of examples from a set of python scripts. | 🟒 | -| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates api reference pages. | 🟒 | +| [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) | Builds an HTML gallery of examples from a set of Python scripts. | 🟒 | +| [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io/en/stable/) | Automatically generates API reference pages. | 🟒 |