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 828c44c.

* style: pre-commit fixes

* chore: disallow RST (-> rST)

Signed-off-by: Henry Schreiner <[email protected]>

---------

Signed-off-by: Henry Schreiner <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Henry Schreiner <[email protected]>

Author: 3 people

.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

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

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

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"