From 80540dfe3d55869ab98153fae52631aaea7608b6 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 4 Jun 2024 17:18:09 -0500 Subject: [PATCH 1/7] update theme-related text in documentation guide --- docs/pages/guides/docs.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 9a9b0d65..d4f6c767 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 @@ -108,7 +108,7 @@ exclude_patterns = [ ".venv", ] -html_theme = "furo" +html_theme = "pydata_sphinx_theme" myst_enable_extensions = [ "colon_fence", @@ -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 From 76bdf002bdf36431a79a3a8275071c8b0a98598b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 4 Jun 2024 22:19:00 +0000 Subject: [PATCH 2/7] style: pre-commit fixes --- docs/pages/guides/docs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index d4f6c767..8bbce2cf 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -108,7 +108,7 @@ exclude_patterns = [ ".venv", ] -html_theme = "pydata_sphinx_theme" +html_theme = "furo" myst_enable_extensions = [ "colon_fence", @@ -148,9 +148,9 @@ We are including both possible file extensions. We are also avoiding some common file patterns, just in case. 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. +[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 From 828c44c17c0e94dedb50884d72813cdc62218f34 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Wed, 5 Jun 2024 18:07:06 -0500 Subject: [PATCH 3/7] use pydata theme in conf.py too --- docs/pages/guides/docs.md | 2 +- {{cookiecutter.project_name}}/docs/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 8bbce2cf..6456f3c1 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -220,7 +220,7 @@ Setting a `docs` extra looks like this: ```toml [project.optional-dependencies] docs = [ - "furo", + "pydata_sphinx_theme", "myst_parser >=0.13", "sphinx >=4.0", "sphinx-copybutton", diff --git a/{{cookiecutter.project_name}}/docs/conf.py b/{{cookiecutter.project_name}}/docs/conf.py index 3f65adf2..78016bbd 100644 --- a/{{cookiecutter.project_name}}/docs/conf.py +++ b/{{cookiecutter.project_name}}/docs/conf.py @@ -27,7 +27,7 @@ ".venv", ] -html_theme = "furo" +html_theme = "pydata_sphinx_theme" myst_enable_extensions = [ "colon_fence", From 9695ca275980055df2fdf774ba7bbe3322039c9a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 5 Jun 2024 23:09:11 +0000 Subject: [PATCH 4/7] style: pre-commit fixes --- docs/pages/guides/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 6456f3c1..d47128b0 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -108,7 +108,7 @@ exclude_patterns = [ ".venv", ] -html_theme = "furo" +html_theme = "pydata_sphinx_theme" myst_enable_extensions = [ "colon_fence", From 4cd498f3d461c0fbc93a01c1eff575b6ca3932d1 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Wed, 5 Jun 2024 18:22:23 -0500 Subject: [PATCH 5/7] Revert "use pydata theme in conf.py too" This reverts commit 828c44c17c0e94dedb50884d72813cdc62218f34. --- docs/pages/guides/docs.md | 2 +- {{cookiecutter.project_name}}/docs/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index d47128b0..7eee5042 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -220,7 +220,7 @@ Setting a `docs` extra looks like this: ```toml [project.optional-dependencies] docs = [ - "pydata_sphinx_theme", + "furo", "myst_parser >=0.13", "sphinx >=4.0", "sphinx-copybutton", diff --git a/{{cookiecutter.project_name}}/docs/conf.py b/{{cookiecutter.project_name}}/docs/conf.py index 78016bbd..3f65adf2 100644 --- a/{{cookiecutter.project_name}}/docs/conf.py +++ b/{{cookiecutter.project_name}}/docs/conf.py @@ -27,7 +27,7 @@ ".venv", ] -html_theme = "pydata_sphinx_theme" +html_theme = "furo" myst_enable_extensions = [ "colon_fence", From 4cbbb234dc650b6daebd78fb4973b4d06217b39c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 5 Jun 2024 23:22:47 +0000 Subject: [PATCH 6/7] style: pre-commit fixes --- docs/pages/guides/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md index 7eee5042..8bbce2cf 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -108,7 +108,7 @@ exclude_patterns = [ ".venv", ] -html_theme = "pydata_sphinx_theme" +html_theme = "furo" myst_enable_extensions = [ "colon_fence", From 6f81f44717fba9f6fe8de216e382d4163655e50e Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 10 Jun 2024 17:42:35 -0400 Subject: [PATCH 7/7] chore: disallow RST (-> rST) Signed-off-by: Henry Schreiner --- .pre-commit-config.yaml | 2 +- README.md | 2 +- docs/pages/guides/docs.md | 2 +- src/sp_repo_review/checks/precommit.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3fd4ded9..ba6b8dd1 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 8bbce2cf..4dfb4d60 100644 --- a/docs/pages/guides/docs.md +++ b/docs/pages/guides/docs.md @@ -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 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"