From 88dc8212f740783d4a74b239429c35950a73a8bd Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 10 Jun 2024 16:43:58 -0500 Subject: [PATCH] docs: update theme-related text in documentation guide (#437) * update theme-related text in documentation guide * style: pre-commit fixes * use pydata theme in conf.py too * style: pre-commit fixes * Revert "use pydata theme in conf.py too" This reverts commit 828c44c17c0e94dedb50884d72813cdc62218f34. * style: pre-commit fixes * chore: disallow RST (-> rST) Signed-off-by: Henry Schreiner --------- Signed-off-by: Henry Schreiner Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Henry Schreiner --- .pre-commit-config.yaml | 2 +- README.md | 2 +- docs/pages/guides/docs.md | 13 +++++++------ src/sp_repo_review/checks/precommit.py | 2 +- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 02b73732..a3f215c9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -76,7 +76,7 @@ repos: - id: disallow-caps name: Disallow improper capitalization language: pygrep - entry: PyBind|Numpy|Cmake|CCache|Github|PyTest + entry: PyBind|Numpy|Cmake|CCache|Github|PyTest|RST exclude: (.pre-commit-config.yaml|docs/pages/guides/style\.md)$ - id: disallow-bad-permalinks name: Disallow _ in permalinks diff --git a/README.md b/README.md index ca5bb47c..2c42fb2f 100644 --- a/README.md +++ b/README.md @@ -365,7 +365,7 @@ for family, grp in itertools.groupby(collected.checks.items(), key=lambda x: x[1 - [`PC111`](https://learn.scientific-python.org/development/guides/style#PC111): Uses blacken-docs - [`PC140`](https://learn.scientific-python.org/development/guides/style#PC140): Uses mypy - [`PC160`](https://learn.scientific-python.org/development/guides/style#PC160): Uses codespell -- [`PC170`](https://learn.scientific-python.org/development/guides/style#PC170): Uses PyGrep hooks (only needed if RST present) +- [`PC170`](https://learn.scientific-python.org/development/guides/style#PC170): Uses PyGrep hooks (only needed if rST present) - [`PC180`](https://learn.scientific-python.org/development/guides/style#PC180): Uses prettier - [`PC190`](https://learn.scientific-python.org/development/guides/style#PC190): Uses Ruff - [`PC191`](https://learn.scientific-python.org/development/guides/style#PC191): Ruff show fixes if fixes enabled diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 9a9b0d65..4dfb4d60 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -11,7 +11,7 @@ parent: Topical Guides # Writing documentation Documentation used to require learning reStructuredText (sometimes referred to -as reST / RST), but today we have great choices for documentation in markdown, +as reST / rST), but today we have great choices for documentation in markdown, the same format used by GitHub, Wikipedia, and others. This guide covers Sphinx, and uses the modern MyST plugin to get Markdown support. @@ -29,7 +29,7 @@ and uses the modern MyST plugin to get Markdown support. > based on markdown and HTML. Less support for man pages & PDFs than Sphinx, > since it doesn't use docutils. Has over > [200 plugins](https://github.com/mkdocs/catalog) - they are much easier to -> write than Sphinx. Examples include [hatch](https://hatch.pypa.io), +> write than Sphinx. Example sites include [hatch](https://hatch.pypa.io), > [PDM](https://pdm.fming.dev), > [cibuildwheel](https://cibuildwheel.readthedocs.io), > [Textual](https://textual.textualize.io), and @@ -68,7 +68,7 @@ with render_cookie() as package: Create `docs/` directory within your project (i.e. next to `src/`). There is a sphinx-quickstart tool, but it creates unnecessary files (make/bat, we recommend -a cross-platform noxfile instead), and uses RST instead of Markdown. Instead, +a cross-platform noxfile instead), and uses rST instead of Markdown. Instead, this is our recommended starting point for `conf.py`: ### conf.py @@ -147,9 +147,10 @@ several good extensions: We are including both possible file extensions. We are also avoiding some common file patterns, just in case. -For theme, you have several good options. The clean, light-weight Furo theme is -shown above. Many scientific packages choose the `sphinx-py-data` theme, which -is also a good choice (no dark mode, though). +For theme, many scientific packages choose the +[pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/). The +[Furo theme](https://pradyunsg.me/furo/) is another popular choice. The site +[sphinx-themes.org](https://sphinx-themes.org/) can be used to compare options. We are enabling a useful MyST extension: `colon_fence` allows you to use three colons for directives, which might be highlighted better if the directive diff --git a/src/sp_repo_review/checks/precommit.py b/src/sp_repo_review/checks/precommit.py index e4c713d2..e9a14356 100644 --- a/src/sp_repo_review/checks/precommit.py +++ b/src/sp_repo_review/checks/precommit.py @@ -92,7 +92,7 @@ class PC160(PreCommit): class PC170(PreCommit): - "Uses PyGrep hooks (only needed if RST present)" + "Uses PyGrep hooks (only needed if rST present)" repo = "https://github.com/pre-commit/pygrep-hooks"