From de88a056ba855cb216e7b6e68e3ce75300c1d170 Mon Sep 17 00:00:00 2001 From: mferrera Date: Tue, 29 Oct 2024 13:33:00 +0100 Subject: [PATCH] DOC: Fix pydantic_autosummary for sphinx-rtd >= 3 Also fixes an indentation issue. --- docs/ext/pydantic_autosummary/__init__.py | 2 + docs/ext/pydantic_autosummary/generate.py | 92 +++++++++++++++-------- pyproject.toml | 2 +- src/fmu/dataio/dataio.py | 6 +- 4 files changed, 66 insertions(+), 36 deletions(-) diff --git a/docs/ext/pydantic_autosummary/__init__.py b/docs/ext/pydantic_autosummary/__init__.py index 089f4ff5a..7c1f379a0 100644 --- a/docs/ext/pydantic_autosummary/__init__.py +++ b/docs/ext/pydantic_autosummary/__init__.py @@ -152,6 +152,8 @@ def autosummary_table_visit_html( class FakeApplication: + verbosity = 0 + def __init__(self) -> None: self.doctreedir = None self.events = None diff --git a/docs/ext/pydantic_autosummary/generate.py b/docs/ext/pydantic_autosummary/generate.py index d2669a10b..4c8e956e8 100644 --- a/docs/ext/pydantic_autosummary/generate.py +++ b/docs/ext/pydantic_autosummary/generate.py @@ -24,6 +24,7 @@ import re import sys from os import path +from pathlib import Path from typing import TYPE_CHECKING, Any, NamedTuple import sphinx.locale @@ -151,7 +152,7 @@ def __init__(self, app: Sphinx) -> None: # ``jinja2.ext.i18n`` extension self.env.install_gettext_translations(app.translator) # type: ignore[attr-defined] - def render(self, template_name: str, context: dict) -> str: + def render(self, template_name: str, context: dict[str, Any]) -> str: """Render a template file.""" try: template = self.env.get_template(template_name) @@ -286,7 +287,7 @@ def generate_autosummary_content( imported_members: bool, app: Any, recursive: bool, - context: dict, + context: dict[str, Any], modname: str | None = None, qualname: str | None = None, ) -> str: @@ -505,10 +506,11 @@ def _get_modules( fullname = name + "." + modname try: module = import_module(fullname) - if module and hasattr(module, "__sphinx_mock__"): - continue except ImportError: pass + else: + if module and hasattr(module, "__sphinx_mock__"): + continue items.append(fullname) if public_members is not None: @@ -529,16 +531,18 @@ def generate_autosummary_docs( app: Any = None, overwrite: bool = True, encoding: str = "utf-8", -) -> None: +) -> list[Path]: + """Generate autosummary documentation for the given sources. + + :returns: list of generated files (both new and existing ones) + """ + assert app is not None, "app is required" + showed_sources = sorted(sources) if len(showed_sources) > 20: showed_sources = showed_sources[:10] + ["..."] + showed_sources[-10:] # ----------- pydantic_autosummary change - logger.info( - __("[pydantic_autosummary] generating autosummary for: %s") - % ", ".join(showed_sources) - ) if output_dir: logger.info(__("[pydantic_autosummary] writing to %s") % output_dir) # ----------/ pydantic_autosummary change @@ -552,7 +556,8 @@ def generate_autosummary_docs( items = find_autosummary_in_files(sources) # keep track of new files - new_files = [] + new_files: list[Path] = [] + all_files: list[Path] = [] filename_map = app.config.autosummary_filename_map if app else {} @@ -593,9 +598,7 @@ def generate_autosummary_docs( # ----------/ pydantic_autosummary change continue - context: dict[str, Any] = {} - if app: - context.update(app.config.autosummary_context) + context: dict[str, Any] = {**app.config.autosummary_context} content = generate_autosummary_content( name, @@ -611,34 +614,39 @@ def generate_autosummary_docs( qualname, ) - filename = os.path.join(path, filename_map.get(name, name) + suffix) - if os.path.isfile(filename): - with open(filename, encoding=encoding) as f: + file_path = Path(path, filename_map.get(name, name) + suffix) + all_files.append(file_path) + if file_path.is_file(): + with file_path.open(encoding=encoding) as f: old_content = f.read() if content == old_content: continue if overwrite: # content has changed - with open(filename, "w", encoding=encoding) as f: + with file_path.open("w", encoding=encoding) as f: f.write(content) - new_files.append(filename) + new_files.append(file_path) else: - with open(filename, "w", encoding=encoding) as f: + with open(file_path, "w", encoding=encoding) as f: f.write(content) - new_files.append(filename) + new_files.append(file_path) # descend recursively to new files if new_files: - generate_autosummary_docs( - new_files, - output_dir=output_dir, - suffix=suffix, - base_path=base_path, - imported_members=imported_members, - app=app, - overwrite=overwrite, + all_files.extend( + generate_autosummary_docs( + [str(f) for f in new_files], + output_dir=output_dir, + suffix=suffix, + base_path=base_path, + imported_members=imported_members, + app=app, + overwrite=overwrite, + ) ) + return all_files + # -- Finding documented entries in files --------------------------------------- @@ -848,6 +856,15 @@ def get_parser() -> argparse.ArgumentParser: "(default: %(default)s)" ), ) + parser.add_argument( + "--remove-old", + action="store_true", + dest="remove_old", + default=False, + help=__( + "Remove existing files in the output directory that were not generated" + ), + ) return parser @@ -863,11 +880,9 @@ def main(argv: Sequence[str] = (), /) -> None: if args.templates: app.config.templates_path.append(path.abspath(args.templates)) - app.config.autosummary_ignore_module_all = ( # type: ignore[attr-defined] - not args.respect_module_all - ) + app.config.autosummary_ignore_module_all = not args.respect_module_all - generate_autosummary_docs( + written_files = generate_autosummary_docs( args.source_file, args.output_dir, "." + args.suffix, @@ -875,6 +890,19 @@ def main(argv: Sequence[str] = (), /) -> None: app=app, ) + if args.remove_old: + for existing in Path(args.output_dir).glob(f"**/*.{args.suffix}"): + if existing not in written_files: + try: + existing.unlink() + except OSError as exc: + logger.warning( + __("Failed to remove %s: %s"), + existing, + exc.strerror, + type="autosummary", + ) + if __name__ == "__main__": main(sys.argv[1:]) diff --git a/pyproject.toml b/pyproject.toml index d637f7239..27d9ad2ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -69,7 +69,7 @@ docs = [ "myst-parser", "pydocstyle", "sphinx-autodoc-typehints<1.23", - "sphinx-rtd-theme<3.0.0", + "sphinx-rtd-theme", "sphinx-togglebutton", "Sphinx", "sphinxcontrib-apidoc", diff --git a/src/fmu/dataio/dataio.py b/src/fmu/dataio/dataio.py index 7168cf8a9..396d7d228 100644 --- a/src/fmu/dataio/dataio.py +++ b/src/fmu/dataio/dataio.py @@ -309,9 +309,9 @@ class ExportData: to metadata will from version 0.9 be different (API change) vertical_domain: Optional. String with vertical domain either "time" or "depth" - (default). It is also possible to provide a reference for the vertical scale, - see the domain_reference key. Note that if the ``content`` is "depth" or - "time" the vertical_domain will be set accordingly. + (default). It is also possible to provide a reference for the vertical + scale, see the domain_reference key. Note that if the ``content`` is "depth" + or "time" the vertical_domain will be set accordingly. workflow: Short tag desciption of workflow (as description)