From 8c97fef6563b5aaafb5fde111c51d154d7a4fa99 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sat, 20 Jul 2024 12:57:04 +0100 Subject: [PATCH 01/14] Fix tests for Sphinx 7.4 (#20) --- CHANGES | 5 +++++ sphinxcontrib/htmlhelp/__init__.py | 2 +- tests/roots/test-basic/conf.py | 1 + tests/roots/test-hhc/conf.py | 1 + 4 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index f2e1585..30caf3e 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,8 @@ +Release 2.0.6 (unreleased) +========================== + +* Fix tests for Sphinx 7.4 and later. + Release 2.0.5 (2024-01-13) ========================== diff --git a/sphinxcontrib/htmlhelp/__init__.py b/sphinxcontrib/htmlhelp/__init__.py index dd27da2..36e80b3 100644 --- a/sphinxcontrib/htmlhelp/__init__.py +++ b/sphinxcontrib/htmlhelp/__init__.py @@ -286,7 +286,7 @@ def write_param(name: str, value: str) -> None: f.write('') for (key, group) in index: for title, (refs, subitems, key_) in group: - write_index(title, refs, subitems) + write_index(title, refs, subitems) # type: ignore[arg-type] f.write('\n') diff --git a/tests/roots/test-basic/conf.py b/tests/roots/test-basic/conf.py index e69de29..329280d 100644 --- a/tests/roots/test-basic/conf.py +++ b/tests/roots/test-basic/conf.py @@ -0,0 +1 @@ +project = 'Python' diff --git a/tests/roots/test-hhc/conf.py b/tests/roots/test-hhc/conf.py index 20447e0..7825564 100644 --- a/tests/roots/test-hhc/conf.py +++ b/tests/roots/test-hhc/conf.py @@ -1 +1,2 @@ +project = 'Python' html_short_title = "Sphinx's documentation" From 49998fdc1e911048e35fbf6fe0f135a47d338214 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sat, 20 Jul 2024 12:58:00 +0100 Subject: [PATCH 02/14] Bump to 2.0.6 final --- CHANGES | 2 +- sphinxcontrib/htmlhelp/__init__.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 30caf3e..c4ebd56 100644 --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,4 @@ -Release 2.0.6 (unreleased) +Release 2.0.6 (2024-07-20) ========================== * Fix tests for Sphinx 7.4 and later. diff --git a/sphinxcontrib/htmlhelp/__init__.py b/sphinxcontrib/htmlhelp/__init__.py index 36e80b3..8ac975e 100644 --- a/sphinxcontrib/htmlhelp/__init__.py +++ b/sphinxcontrib/htmlhelp/__init__.py @@ -28,8 +28,8 @@ else: from sphinx.util import progress_message # type: ignore[attr-defined,no-redef] -__version__ = '2.0.5' -__version_info__ = (2, 0, 5) +__version__ = '2.0.6' +__version_info__ = (2, 0, 6) logger = logging.getLogger(__name__) __ = get_translation(__name__, 'console') From c5ec8d7d7ca8520b9f6eac2bfb71f37ddc6eef65 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sat, 27 Jul 2024 18:38:40 +0100 Subject: [PATCH 03/14] Update .gitignore --- .gitignore | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index fe75ce5..10cef94 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,17 @@ *.pyc -*.egg -*.so -*.swp .DS_Store +idea/ +.vscode/ + .mypy_cache/ +.pytest_cache/ +.ruff_cache/ .tags .tox/ +.venv/ +venv/ + build/ dist/ -sphinxcontrib_htmlhelp.egg-info/ From a21bb3dc83b14ee2518dc548229f9902ea7aadcc Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 28 Jul 2024 05:02:28 +0100 Subject: [PATCH 04/14] Adopt Ruff and use stricter MyPy settings --- .flake8 | 4 -- .github/workflows/test.yml | 4 +- .ruff.toml | 53 +++++++++++++++ Makefile | 2 +- pyproject.toml | 36 +++++++++- sphinxcontrib/htmlhelp/__init__.py | 105 ++++++++++++++++------------- sphinxcontrib/htmlhelp/py.typed | 0 tests/conftest.py | 15 ++--- tests/roots/test-basic/conf.py | 2 + tests/roots/test-chm/conf.py | 2 + tests/roots/test-hhc/conf.py | 2 + tests/test_htmlhelp.py | 42 +++++++----- tox.ini | 6 +- 13 files changed, 188 insertions(+), 85 deletions(-) delete mode 100644 .flake8 create mode 100644 .ruff.toml create mode 100644 sphinxcontrib/htmlhelp/py.typed diff --git a/.flake8 b/.flake8 deleted file mode 100644 index 5af0a95..0000000 --- a/.flake8 +++ /dev/null @@ -1,4 +0,0 @@ -[flake8] -max-line-length = 95 -ignore = E116,E241,E251 -exclude = .git,.tox,.venv diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8cd7db1..856df5b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -71,7 +71,9 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - env: [flake8, mypy] + env: + - ruff + - mypy steps: - uses: actions/checkout@v3 diff --git a/.ruff.toml b/.ruff.toml new file mode 100644 index 0000000..4b7dd2a --- /dev/null +++ b/.ruff.toml @@ -0,0 +1,53 @@ +target-version = "py39" # Pin Ruff to Python 3.9 +output-format = "full" +line-length = 95 + +[lint] +preview = true +select = [ +# "ANN", # flake8-annotations + "C4", # flake8-comprehensions + "COM", # flake8-commas + "B", # flake8-bugbear + "DTZ", # flake8-datetimez + "E", # pycodestyle + "EM", # flake8-errmsg + "EXE", # flake8-executable + "F", # pyflakes + "FA", # flake8-future-annotations + "FLY", # flynt + "FURB", # refurb + "G", # flake8-logging-format + "I", # isort + "ICN", # flake8-import-conventions + "INT", # flake8-gettext + "LOG", # flake8-logging + "PERF", # perflint + "PGH", # pygrep-hooks + "PIE", # flake8-pie + "PT", # flake8-pytest-style + "SIM", # flake8-simplify + "SLOT", # flake8-slots + "TCH", # flake8-type-checking + "UP", # pyupgrade + "W", # pycodestyle + "YTT", # flake8-2020 +] +ignore = [ + "E116", + "E241", + "E251", +] + +[lint.per-file-ignores] +"tests/*" = [ + "ANN", # tests don't need annotations +] + +[lint.isort] +forced-separate = [ + "tests", +] +required-imports = [ + "from __future__ import annotations", +] diff --git a/Makefile b/Makefile index 26f411a..438ee54 100644 --- a/Makefile +++ b/Makefile @@ -47,7 +47,7 @@ clean-mypyfiles: .PHONY: style-check style-check: - @flake8 + @ruff check .PHONY: type-check type-check: diff --git a/pyproject.toml b/pyproject.toml index fb933af..5db9843 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,9 +48,9 @@ test = [ "html5lib", ] lint = [ - "flake8", + "ruff==0.5.5", "mypy", - "docutils-stubs", + "types-docutils", ] standalone = [ "Sphinx>=5", @@ -73,4 +73,34 @@ include = [ ] [tool.mypy] -ignore_missing_imports = true +python_version = "3.9" +packages = [ + "sphinxcontrib", + "tests", +] +exclude = [ + "tests/roots", +] +check_untyped_defs = true +disallow_any_generics = true +disallow_incomplete_defs = true +disallow_subclassing_any = true +disallow_untyped_calls = true +disallow_untyped_decorators = true +disallow_untyped_defs = true +#explicit_package_bases = true +extra_checks = true +no_implicit_reexport = true +show_column_numbers = true +show_error_context = true +strict_optional = true +warn_redundant_casts = true +warn_unused_configs = true +warn_unused_ignores = true +enable_error_code = [ + "type-arg", + "redundant-self", + "truthy-iterable", + "ignore-without-code", + "unused-awaitable", +] diff --git a/sphinxcontrib/htmlhelp/__init__.py b/sphinxcontrib/htmlhelp/__init__.py index 8ac975e..90c61bb 100644 --- a/sphinxcontrib/htmlhelp/__init__.py +++ b/sphinxcontrib/htmlhelp/__init__.py @@ -5,16 +5,13 @@ import html import os from os import path -from typing import Any - -from docutils import nodes -from docutils.nodes import Element, Node, document +from pathlib import Path +from typing import TYPE_CHECKING, Any import sphinx +from docutils import nodes from sphinx import addnodes -from sphinx.application import Sphinx from sphinx.builders.html import StandaloneHTMLBuilder -from sphinx.config import Config from sphinx.environment.adapters.indexentries import IndexEntries from sphinx.locale import get_translation from sphinx.util import logging @@ -23,10 +20,15 @@ from sphinx.util.osutil import make_filename_from_project, relpath from sphinx.util.template import SphinxRenderer +if TYPE_CHECKING: + from docutils.nodes import Element, Node, document + from sphinx.application import Sphinx + from sphinx.config import Config + if sphinx.version_info[:2] >= (6, 1): from sphinx.util.display import progress_message else: - from sphinx.util import progress_message # type: ignore[attr-defined,no-redef] + from sphinx.util import progress_message # type: ignore[no-redef] __version__ = '2.0.6' __version_info__ = (2, 0, 6) @@ -126,8 +128,8 @@ def depart_list_item(self, node: Element) -> None: def visit_reference(self, node: Element) -> None: title = chm_htmlescape(node.astext(), True) - self.append(' ' % title) - self.append(' ' % node['refuri']) + self.append(f' ') + self.append(f' ') self.append('') raise nodes.SkipNode @@ -170,7 +172,13 @@ def prepare_writing(self, docnames: set[str]) -> None: super().prepare_writing(docnames) self.globalcontext['html5_doctype'] = False - def update_page_context(self, pagename: str, templatename: str, ctx: dict, event_arg: str) -> None: # NOQA + def update_page_context( + self, + pagename: str, + templatename: str, + ctx: dict[str, Any], + event_arg: str, + ) -> None: ctx['encoding'] = self.encoding def handle_finish(self) -> None: @@ -180,14 +188,14 @@ def handle_finish(self) -> None: self.build_hhx(self.outdir, self.config.htmlhelp_basename) def write_doc(self, docname: str, doctree: document) -> None: - for node in doctree.traverse(nodes.reference): + for node in doctree.findall(nodes.reference): # add ``target=_blank`` attributes to external links if node.get('internal') is None and 'refuri' in node: node['target'] = '_blank' super().write_doc(docname, doctree) - def render(self, name: str, context: dict) -> str: + def render(self, name: str, context: dict[str, Any]) -> str: template = SphinxRenderer(template_dir) return template.render(name, context) @@ -220,40 +228,39 @@ def build_project_file(self) -> None: fn = relpath(path.join(root, fn), self.outdir) project_files.append(fn.replace(os.sep, '\\')) - filename = path.join(self.outdir, self.config.htmlhelp_basename + '.hhp') - with open(filename, 'w', encoding=self.encoding, errors='xmlcharrefreplace') as f: - context = { - 'outname': self.config.htmlhelp_basename, - 'title': self.config.html_title, - 'version': self.config.version, - 'project': self.config.project, - 'lcid': self.lcid, - 'master_doc': self.config.master_doc + self.out_suffix, - 'files': project_files, - } - body = self.render('project.hhp', context) - f.write(body) + context = { + 'outname': self.config.htmlhelp_basename, + 'title': self.config.html_title, + 'version': self.config.version, + 'project': self.config.project, + 'lcid': self.lcid, + 'master_doc': self.config.master_doc + self.out_suffix, + 'files': project_files, + } + body = self.render('project.hhp', context) + filename = Path(self.outdir, f'{self.config.htmlhelp_basename}.hhp') + filename.write_text(body, encoding=self.encoding, errors='xmlcharrefreplace') @progress_message(__('writing TOC file')) def build_toc_file(self) -> None: """Create a ToC file (.hhp) on outdir.""" - filename = path.join(self.outdir, self.config.htmlhelp_basename + '.hhc') - with open(filename, 'w', encoding=self.encoding, errors='xmlcharrefreplace') as f: - toctree = self.env.get_and_resolve_doctree(self.config.master_doc, self, - prune_toctrees=False) - visitor = ToCTreeVisitor(toctree) - matcher = NodeMatcher(addnodes.compact_paragraph, toctree=True) - for node in toctree.traverse(matcher): # type: addnodes.compact_paragraph - node.walkabout(visitor) - - context = { - 'body': visitor.astext(), - 'suffix': self.out_suffix, - 'short_title': self.config.html_short_title, - 'master_doc': self.config.master_doc, - 'domain_indices': self.domain_indices, - } - f.write(self.render('project.hhc', context)) + toctree = self.env.get_and_resolve_doctree(self.config.master_doc, self, + prune_toctrees=False) + visitor = ToCTreeVisitor(toctree) + matcher = NodeMatcher(addnodes.compact_paragraph, toctree=True) + for node in toctree.findall(matcher): + node.walkabout(visitor) + + context = { + 'body': visitor.astext(), + 'suffix': self.out_suffix, + 'short_title': self.config.html_short_title, + 'master_doc': self.config.master_doc, + 'domain_indices': self.domain_indices, + } + body = self.render('project.hhc', context) + filename = Path(self.outdir, f'{self.config.htmlhelp_basename}.hhc') + filename.write_text(body, encoding=self.encoding, errors='xmlcharrefreplace') def build_hhx(self, outdir: str | os.PathLike[str], outname: str) -> None: logger.info(__('writing index file...')) @@ -262,9 +269,13 @@ def build_hhx(self, outdir: str | os.PathLike[str], outname: str) -> None: with open(filename, 'w', encoding=self.encoding, errors='xmlcharrefreplace') as f: f.write('