docs: convert documentation from rst to google style by martynia · Pull Request #965 · DIRACGrid/diracx

martynia · 2026-07-01T18:45:50Z

Adding google-style documentation. Addresses #927

read-the-docs-community · 2026-07-01T18:46:52Z

Documentation build overview

📚 diracx | 🛠️ Build #33430774 | 📁 Comparing 16d2d74 against latest (b8db2cc)

🔍 Preview build

1 file changed

± admin/reference/env-variables/index.html

for more information, see https://pre-commit.ci

devlink42 · 2026-07-03T11:47:15Z

+            vo (Optional[str]): Virtual Organization name (validated by `vo_callback`).
+            group (Optional[str]): Group name within the VO.
+            property (Optional[list[str]]): Additional properties to request.


Suggested change

vo (Optional[str]): Virtual Organization name (validated by `vo_callback`).

group (Optional[str]): Group name within the VO.

property (Optional[list[str]]): Additional properties to request.

vo (Optional[str]): Virtual Organization name (validated by `vo_callback`).

group (Optional[str]): Group name within the VO.

property (Optional[list[str]]): Additional properties to request.

devlink42 · 2026-07-03T11:47:34Z

+            property (Optional[list[str]]): Additional properties to request.
+
+    Raises:
+            RuntimeError: If the device flow fails or expires before completion.


Suggested change

RuntimeError: If the device flow fails or expires before completion.

RuntimeError: If the device flow fails or expires before completion.

devlink42 · 2026-07-03T11:52:04Z

+
+    Returns:
+        None


Do we really need to put 'Returns: None' when it returns nothing? You didn't put it for the previous file, so should we always put it or never put it? I don't know what the best approach is or what we want.

devlink42 · 2026-07-03T11:54:05Z

+    `NotImplementedError`.
+
+    Args:
+        data: Arbitrary JSON-serializable data to display.


Why don't you put the type here?

devlink42 · 2026-07-03T11:57:13Z

+    The class understands headers of the form ``"unit start-end/total"``
+    (e.g. ``"jobs 0-9/100"``) and exposes parsed attributes suitable for
+    building human-readable captions for CLI output.
+    """


You can probably add Attributes: for unit, start, end and total?

Suggested change

"""

Attributes:

unit (str | None): The unit of the range (e.g., "bytes", "items", "jobs").

start (int | None): The starting index of the requested range.

end (int | None): The ending index of the requested range.

total (int | None): The total number of items available.

"""

devlink42 · 2026-07-03T16:43:22Z


    scheme = "git+file"

    def __init__(self, *, backend_url: ConfigSourceUrl) -> None:


Suggested change

def __init__(self, *, backend_url: ConfigSourceUrl) -> None:

"""Initialize the local Git configuration source.

Args:

backend_url (ConfigSourceUrl): The URL containing the repository path.

Raises:

ValueError: If the backend URL does not contain a valid path,

or if the provided path is not a valid Git repository.

"""

devlink42 · 2026-07-03T16:44:06Z


 class BaseGitConfigSource(ConfigSource):
-    """Base class for the git based config source."""
+    """Base class for Git-backed configuration sources."""


Suggested change

"""Base class for Git-backed configuration sources."""

"""Base class for Git-backed configuration sources.

Attributes:

repo_location (Path): The local file system path where the repository is stored.

scheme (str): The URL scheme identifier required by the parent registry.

remote_url (str): The extracted remote URL for the Git repository.

git_revision (str): The specific Git revision (branch, tag, or commit) to use.

"""

devlink42 · 2026-07-03T16:45:21Z

    __registry: dict[str, type["ConfigSource"]] = {}
    scheme: str

    def __init__(self, *, backend_url: ConfigSourceUrl) -> None:


Suggested change

def __init__(self, *, backend_url: ConfigSourceUrl) -> None:

"""Initialize the Git-backed configuration source.

Args:

backend_url (ConfigSourceUrl): The backend URL containing the Git

configuration parameters.

"""

devlink42 · 2026-07-03T16:46:21Z

        self.remote_url = self.extract_remote_url(backend_url)
        self.git_revision = self.get_git_revision_from_url(backend_url)

    def latest_revision(self) -> tuple[str, datetime]:


Suggested change

def latest_revision(self) -> tuple[str, datetime]:

"""Retrieve the latest Git revision hash and its modification timestamp.

Returns:

tuple[str, datetime]: A tuple containing the commit hash (str) and

the exact modification timestamp (datetime) of the latest revision.

Raises:

BadConfigurationVersionError: If the underlying Git commands fail to

parse the revision or retrieve the commit information.

"""

devlink42 · 2026-07-03T16:47:47Z

        return rev, modified

    def read_raw(self, hexsha: str, modified: datetime) -> Config:
        """:param: hexsha commit hash"""


Suggested change

"""Read and parse the raw configuration from a specific Git commit.

Args:

hexsha (str): The Git commit hash to read the configuration from.

modified (datetime): The modification timestamp associated with the commit.

Returns:

Config: The validated configuration object populated with the repository data.

Raises:

BadConfigurationVersionError: If the Git command fails to locate or read

the specified configuration blob.

"""

aldbr linked an issue Jul 2, 2026 that may be closed by this pull request

Enhancement: Harmonize Docstring convention to Google Style (Native MkDocs Support & CI Enforcement) #927

Open

aldbr marked this pull request as draft July 2, 2026 08:04

aldbr changed the title ~~Janusz googledocs 927~~ docs: convert documentation from rst to google style 927 Jul 2, 2026

aldbr changed the title ~~docs: convert documentation from rst to google style 927~~ docs: convert documentation from rst to google style Jul 2, 2026

martynia force-pushed the janusz_googledocs_927 branch from c75ab7d to 7cdb0a0 Compare July 3, 2026 16:18

martynia added 24 commits July 3, 2026 18:19

docs: enforce google docs style

4d0ddc7

docs: enforce google docs style - 1

d9ec04a

docs: enforce google docs style - access_policies.py

87a0c72

docs: enforce google docs style - cli

3a2cb28

docs: enforce google docs style - db/exceptions.py

519f14c

docs: enforce google docs style - db/exceptions.py (fix module doc)

88763ad

docs: enforce google docs style - os/job_parameters

a0178a5

docs: enforce google docs style - os/utils

dd9db41

docs: enforce google docs style - os/utils

ca9607a

docs: enforce google docs style - db/sql/auth/db.py

d88be6a

docs: enforce google docs style - db/sql/dummy/db.py

fd4a3e1

docs: enforce google docs style - db/sql/job

58ff096

docs: enforce google docs style - db/sql/job_logging

6b129ed

docs: enforce google docs style - db/sql/rss

586836d

docs: enforce google docs style - db/sql/sandbox_metadata

33b2e0b

docs: enforce google docs style - db/sql/rss/schema.py

f37c441

docs: enforce google docs style - db/sql/task_queue

071634a

docs: enforce google docs style - db/sql/utils

45ca67d

docs: enforce google docs style - logic/auth

379723c

docs: enforce google docs style - logic/jobs

9bdd59a

docs: enforce google docs style - logic/rss/query

bfa07e9

docs: enforce google docs style - logic/task_queues/priority.py

d3959a0

docs: enforce google docs style - routers/auth

be1704a

docs: enforce google docs style - routers/jobs

5ffe824

martynia added 4 commits July 3, 2026 18:21

docs: enforce google docs style - /db/sql/pilot_agents

67c9d6c

docs: enforce google docs style - core

0ad09e0

docs: add comments to s3

9b7cb6e

docs: add CacheableSource

555c833

martynia force-pushed the janusz_googledocs_927 branch from 7cdb0a0 to 555c833 Compare July 3, 2026 16:25

[pre-commit.ci] auto fixes from pre-commit.com hooks

16d2d74

for more information, see https://pre-commit.ci

devlink42 reviewed Jul 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: convert documentation from rst to google style#965

docs: convert documentation from rst to google style#965
martynia wants to merge 29 commits into
DIRACGrid:mainfrom
martynia:janusz_googledocs_927

martynia commented Jul 1, 2026

Uh oh!

read-the-docs-community Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

devlink42 Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	RuntimeError: If the device flow fails or expires before completion.
	RuntimeError: If the device flow fails or expires before completion.

-    """
+    Attributes:
+        unit (str | None): The unit of the range (e.g., "bytes", "items", "jobs").
+        start (int | None): The starting index of the requested range.
+        end (int | None): The ending index of the requested range.
+        total (int | None): The total number of items available.
+    """


		scheme = "git+file"

		def __init__(self, *, backend_url: ConfigSourceUrl) -> None:

+    def __init__(self, *, backend_url: ConfigSourceUrl) -> None:
+        """Initialize the local Git configuration source.
+        Args:
+            backend_url (ConfigSourceUrl): The URL containing the repository path.
+        Raises:
+            ValueError: If the backend URL does not contain a valid path,
+                or if the provided path is not a valid Git repository.
+        """

-    """Base class for Git-backed configuration sources."""
+    """Base class for Git-backed configuration sources.
+    Attributes:
+        repo_location (Path): The local file system path where the repository is stored.
+        scheme (str): The URL scheme identifier required by the parent registry.
+        remote_url (str): The extracted remote URL for the Git repository.
+        git_revision (str): The specific Git revision (branch, tag, or commit) to use.
+    """

+    def __init__(self, *, backend_url: ConfigSourceUrl) -> None:
+        """Initialize the Git-backed configuration source.
+        Args:
+            backend_url (ConfigSourceUrl): The backend URL containing the Git
+                configuration parameters.
+        """

+    def latest_revision(self) -> tuple[str, datetime]:
+        """Retrieve the latest Git revision hash and its modification timestamp.
+        Returns:
+            tuple[str, datetime]: A tuple containing the commit hash (str) and
+                the exact modification timestamp (datetime) of the latest revision.
+        Raises:
+            BadConfigurationVersionError: If the underlying Git commands fail to
+                parse the revision or retrieve the commit information.
+        """

+        """Read and parse the raw configuration from a specific Git commit.
+        Args:
+            hexsha (str): The Git commit hash to read the configuration from.
+            modified (datetime): The modification timestamp associated with the commit.
+        Returns:
+            Config: The validated configuration object populated with the repository data.
+        Raises:
+            BadConfigurationVersionError: If the Git command fails to locate or read
+                the specified configuration blob.
+        """

Uh oh!

Conversation

martynia commented Jul 1, 2026

Uh oh!

read-the-docs-community Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

read-the-docs-community Bot commented Jul 1, 2026 •

edited

Loading