Merge pull request #135 from openSUSE/toms/reformat-code-with-ruff

Reformat source code with Ruff

Author: tomschr

.ruff.toml

@@ -55,7 +55,7 @@ ignore = [
     "D203",    # Conflicts with D211 (one blank line before class docstring)
     "D213",    # Conflicts with D212 (multi-line docstring start convention)
     # "D401",    # First line of docstring should be in imperative mood
-    "COM812",  # 
+    "COM812",  #
 ]
 
 # Allow autofix for everything except complexity and annotations
@@ -77,7 +77,7 @@ max-complexity = 10
 
 [format]
 # 5. Use single quotes in `ruff format`.
-quote-style = "single"
+quote-style = "double"
 
 
 [lint.per-file-ignores]
@@ -91,8 +91,11 @@ quote-style = "single"
     "ANN201", # Missing return type annotation
     "ANN202", # Missing return type annotation for private function
     "ANN204", # Missing return type annotation for special method `__init__`
+    "ANN401", # Missing type annotation for self in method
     "D100",   # Missing docstring in public module
     "D101",   # Missing docstring in public class
     "D103",   # Missing docstring in public function
     "D105",   # Missing docstring in magic method
-]
+]
+# Ignore unused imports in all __init__.py files
+"__init__.py" = ["F401"]

GEMINI.md

@@ -0,0 +1,20 @@
+# Project: Docbuild
+
+Docbuild is a project to build documentation either from DocBook or ADoc code. It maintains a set of XML configuration files, clones the repositories, calls the `daps` executable, takes care of metadata and syncs the result deliverables to its target directory.
+
+## General instructions
+
+- Make minimal changes
+- Leave the code base untouched as much as possible
+
+## Coding Standards
+
+Ensure the generated code conforms to these points:
+
+- Python Version: Use Python 3.12 or higher. Adapt code style, type hints, and docstrings accordingly.
+
+- Type Hints: Use type hints for functions and variables where feasible.
+
+- Docstrings: Add Sphinx-style docstrings. Document the purpose of the code in a short line, followed by the arguments and their purpose.
+
+- Clarity & Maintainability: Focus on clean, maintainable code. Adhere to the single responsibility principle (one function, one purpose).

changelog.d/135.infra.rst

@@ -0,0 +1 @@
+Reformat the source code with Ruff. Removed unused imports and variables, fix docstrings, and use double quotes in strings.

docs/source/conf.py

@@ -8,17 +8,17 @@
 
 from docbuild.__about__ import __version__
 
-project = 'docbuild'
-copyright = '2025, Tom Schraitle'  # noqa: A001
-author = 'Tom Schraitle'
+project = "docbuild"
+copyright = "2025, Tom Schraitle"  # noqa: A001
+author = "Tom Schraitle"
 release = __version__
 
-gh_user = 'openSUSE'
-gh_repo_url = f'https://github.com/{gh_user}/{project}'
-gh_repo_slug = f'{gh_user}/{project}'
+gh_user = "openSUSE"
+gh_repo_url = f"https://github.com/{gh_user}/{project}"
+gh_repo_slug = f"{gh_user}/{project}"
 
-xml_config_repo = 'https://gitlab.suse.de/susedoc/docserv-config'
-xml_config_slug = '/'.join(xml_config_repo.rsplit('/', 2)[-2:])
+xml_config_repo = "https://gitlab.suse.de/susedoc/docserv-config"
+xml_config_slug = "/".join(xml_config_repo.rsplit("/", 2)[-2:])
 
 # --- Prolog configuration
 rst_prolog = f"""
@@ -39,87 +39,87 @@
 extensions = [
     # Include documentation from docstrings
     # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
-    'sphinx.ext.autodoc',
+    "sphinx.ext.autodoc",
     #
     # Link to other projects' documentation
     # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
-    'sphinx.ext.intersphinx',
+    "sphinx.ext.intersphinx",
     #
     # Test code snippets in the documentation
     # https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
-    'sphinx.ext.doctest',
+    "sphinx.ext.doctest",
     #
     # Create short aliases for external links
     # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
-    'sphinx.ext.extlinks',
+    "sphinx.ext.extlinks",
     #
     # Embed Graphviz graphs
     # https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
-    'sphinx.ext.graphviz',
+    "sphinx.ext.graphviz",
     #
     # Document Click command-line interfaces
     # https://sphinx-click.readthedocs.io/en/latest/
-    'sphinx_click',
+    "sphinx_click",
     #
     # Add a "copy" button to code blocks
     # https://sphinx-copybutton.readthedocs.io/en/latest/
-    'sphinx_copybutton',
+    "sphinx_copybutton",
     #
     # Render type hints in signatures
     # https://github.com/tox-dev/sphinx-autodoc-typehints
-    'sphinx_autodoc_typehints',
+    "sphinx_autodoc_typehints",
     #
     # Generate API documentation from source code
     # https://sphinx-autoapi.readthedocs.io/en/latest/
-    'autoapi.extension',
+    "autoapi.extension",
 ]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
-language = 'en'
+language = "en"
 
 # -- Options for autoapi extension
 # https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
 autoapi_modules = {
-    'docbuild': None,
+    "docbuild": None,
     # {
     #     # "output": "reference/_autoapi",
     #     # "prune": True|False,
     #     # "override": True|False,
     #     # "template":
     # }
 }
-autoapi_root = 'reference/_autoapi'
-autoapi_dirs = ['../../src/']
-autoapi_type = 'python'
+autoapi_root = "reference/_autoapi"
+autoapi_dirs = ["../../src/"]
+autoapi_type = "python"
 autoapi_add_toctree_entry = False
 # autoapi_template_dir = "_templates/autoapi"
 autoapi_options = [
-    'members',
+    "members",
     # "undoc-members",
     # 'inherited-members',
-    'show-inheritance',
-    'show-module-summary',
+    "show-inheritance",
+    "show-module-summary",
     # 'imported-members',
-    'special-members',
-    'show-inheritance-diagram',  # needs sphinx.ext.inheritance_diagram & graphviz
+    "special-members",
+    "show-inheritance-diagram",  # needs sphinx.ext.inheritance_diagram & graphviz
     # "private-members",
 ]
 autoapi_keep_files = True
-autodoc_typehints = 'signature'
-autoapi_own_page_level = 'class'
-#autoapi_python_use_implicit_namespaces = True
+autodoc_typehints = "signature"
+autoapi_own_page_level = "class"
+# autoapi_python_use_implicit_namespaces = True
 
 # -- Options for extlinks extension ------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
     # Example for linking to a specific file/path in the repo:
-    'gh_path': (f'{gh_repo_url}/blob/main/%s', '%s'),
+    "gh_path": (f"{gh_repo_url}/blob/main/%s", "%s"),
     # Example for linking to a specific directory in the repo:
-    'gh_tree': (f'{gh_repo_url}/tree/main/%s', '%s'),
+    "gh_tree": (f"{gh_repo_url}/tree/main/%s", "%s"),
     # Linking to the GH issue tracker:
-    'gh': (f'{gh_repo_url}/issues/%s', 'GH #%s'),
+    "gh": (f"{gh_repo_url}/issues/%s", "GH #%s"),
 }
 
 
@@ -129,90 +129,90 @@
 
 autosummary_generate = False
 autodoc_default_options = {
-    'members': True,
-    'undoc-members': False,
-    'show-inheritance': True,
-    'inherited-members': False,
-    'private-members': True,
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+    "inherited-members": False,
+    "private-members": True,
 }
 
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 # html_theme = "alabaster"
 
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 html_css_files = [
-    'css/custom.css',
+    "css/custom.css",
 ]
 
 html_context = {
-    'github_user': gh_user,
-    'github_repo': project,
-    'github_version': 'main',
-    'doc_path': 'docs/source/',
+    "github_user": gh_user,
+    "github_repo": project,
+    "github_version": "main",
+    "doc_path": "docs/source/",
 }
 
 html_theme_options = {
-    'announcement': 'Documentation is under construction.',
-    'show_prev_next': True,
+    "announcement": "Documentation is under construction.",
+    "show_prev_next": True,
     # "html_last_updated_fmt": "%b %d, %Y",
-    'content_footer_items': ['last-updated'],
-    'github_url': gh_repo_url,
+    "content_footer_items": ["last-updated"],
+    "github_url": gh_repo_url,
     #   "external_links": [
     #       {"name": "link-one-name", "url": "https://<link-one>"},
     #   ],
     #
-    'icon_links': [
+    "icon_links": [
         {
-            'name': 'GitLab susedoc/docserv-config',
-            'url': xml_config_repo,
-            'icon': 'fa-brands fa-square-gitlab',
-            'type': 'fontawesome',
+            "name": "GitLab susedoc/docserv-config",
+            "url": xml_config_repo,
+            "icon": "fa-brands fa-square-gitlab",
+            "type": "fontawesome",
         },
         {
-            'name': 'Kanban board',
-            'url': 'https://github.com/orgs/openSUSE/projects/27/',
-            'icon': 'fa-solid fa-table-columns',
-            'type': 'fontawesome',
+            "name": "Kanban board",
+            "url": "https://github.com/orgs/openSUSE/projects/27/",
+            "icon": "fa-solid fa-table-columns",
+            "type": "fontawesome",
         },
     ],
     #
-    'use_edit_page_button': True,
-    'back_to_top_button': True,
-    'logo': {
-        'text': 'Docbuild Documentation',
+    "use_edit_page_button": True,
+    "back_to_top_button": True,
+    "logo": {
+        "text": "Docbuild Documentation",
         # "image_light": "_static/logo-light.png",
         # "image_dark": "_static/logo-dark.png",
     },
 }
 
-html_logo = '_static/logo.png'
+html_logo = "_static/logo.png"
 
-html_favicon = '_static/favicon.ico'
+html_favicon = "_static/favicon.ico"
 
 # -- Options for intersphinx extension ---------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
-    'pydantic': ('https://docs.pydantic.dev/latest/', None),
-    'click': ('https://click.palletsprojects.com/en/latest/', None),
-    'jinja2': ('https://jinja.palletsprojects.com/en/latest/', None),
+    "python": ("https://docs.python.org/3", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
+    "click": ("https://click.palletsprojects.com/en/latest/", None),
+    "jinja2": ("https://jinja.palletsprojects.com/en/latest/", None),
 }
 
 # -- Options for linkcheck builder --------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
 linkcheck_ignore = [
     # Ignore links to the internal GitLab server, which may require a VPN or login.
-    r'https://gitlab\.suse\.de/.*',
+    r"https://gitlab\.suse\.de/.*",
     # Ignore links to local development servers.
-    r'http://127\.0\.0\.1:\d+/',
-    r'http://localhost:\d+/',
+    r"http://127\.0\.0\.1:\d+/",
+    r"http://localhost:\d+/",
     # Ignore mailto links
-    r'mailto:.*',
+    r"mailto:.*",
     # Ignore settings page as only admins have access
-    rf'https://github\.com/{gh_user}/{project}/settings/rules',
+    rf"https://github\.com/{gh_user}/{project}/settings/rules",
     # Just ignore useless example URLs
-    r'https://github\.com/org/repo',
+    r"https://github\.com/org/repo",
 ]

src/docbuild/__about__.py

@@ -3,7 +3,7 @@
 This module contains metadata about the package, including its version and authors.
 """
 
-__version__ = '0.14.0'
+__version__ = "0.14.0"
 __authors__ = [
-    'Tom Schraitle <[email protected]>',
+    "Tom Schraitle <[email protected]>",
 ]

src/docbuild/__main__.py

@@ -2,5 +2,5 @@
 
 from .cli.cmd_cli import cli
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     cli()

src/docbuild/cli/callback.py

@@ -1,3 +1,5 @@
+"""Click callback to validate doctype strings."""
+
 import logging
 
 import click
@@ -40,39 +42,39 @@ def validate_doctypes(
         except ValueError as err:
             click.secho(
                 f"ERROR: Invalid doctype string '{doctype_str}': {err}",
-                fg='red',
+                fg="red",
                 err=True,
             )
             raise click.Abort(err) from err
 
         except ValidationError as err:
             for error in err.errors():
-                field = error['loc'][0]
+                field = error["loc"][0]
                 # Convert to string to ensure it works as dictionary key
                 field_name = str(field)
-                msg = error['msg']
+                msg = error["msg"]
                 # Make accessing of .description and .examples safe(r) if
                 # the definition in Doctype is not present
                 safe_field = Field(description=None, examples=None)
                 hint = getattr(
                     Doctype.model_fields.get(field_name, safe_field),
-                    'description',
+                    "description",
                     None,
                 )
                 examples = getattr(
                     Doctype.model_fields.get(field_name, safe_field),
-                    'examples',
+                    "examples",
                     None,
                 )
                 click.secho(
                     f"ERROR in '{field}': {msg}",
-                    fg='red',
+                    fg="red",
                     err=True,
                 )
                 if hint:
-                    click.echo(f'  → Hint: {hint}')
+                    click.echo(f"  → Hint: {hint}")
                 if examples:
-                    click.echo(f'  → Examples: {", ".join(examples)}')
+                    click.echo(f"  → Examples: {', '.join(examples)}")
                 click.echo()
             raise click.Abort(err) from err