gdtest-stress-all-docstr

Stress test with every docstring feature.

Module with every docstring feature: RST directives, Sphinx roles, all NumPy sections, math, tables, examples, code blocks. Post-render should handle everything.

Source files

📁 gdtest_stress_all_docstr/

📄 __init__.py

"""Package stress-testing every docstring feature."""

__all__ = ["mega_function", "other_func", "DataHolder"]


def mega_function(data: list, mode: str = "default", threshold: float = 0.5) -> dict:
    r"""Perform a mega computation combining all docstring features.

    Applies a configurable analysis pipeline to the input data,
    returning detailed results. Uses :py:func:`other_func` for
    element-wise transformations and :py:class:`DataHolder` for
    result storage.

    .. versionadded:: 3.0

    .. note:: This replaces the old API.

    Parameters
    ----------
    data : list
        A list of numeric values to process. Must contain at
        least one element.
    mode : str, optional
        The processing mode. One of ``"default"`` or ``"strict"``.
        Defaults to ``"default"``.
    threshold : float, optional
        The minimum threshold for filtering values. Values below
        this threshold are excluded. Defaults to ``0.5``.

    Returns
    -------
    dict
        A dictionary with the following keys:

        - ``"result"`` — the computed aggregate value (float).
        - ``"filtered"`` — data points above threshold (list).
        - ``"mode"`` — the mode that was used (str).
        - ``"count"`` — number of points processed (int).

    Raises
    ------
    ValueError
        If ``data`` is empty or ``mode`` is not recognized.

    Notes
    -----
    The ``"default"`` mode applies a simple mean calculation:

    .. math::

        R = \frac{1}{n} \sum_{i=1}^{n} f(x_i)

    where :math:`f` is the :py:func:`other_func` transformation.

    The ``"strict"`` mode additionally filters values below the
    ``threshold`` before computing the mean. This can significantly
    reduce the number of data points in the output.

    The time complexity is ``O(n)`` for both modes. Memory usage
    is proportional to the size of the input data.

    Warnings
    --------
    Input is modified in-place when ``mode="strict"`` is used.
    Make a copy of the data before calling if you need to preserve
    the original values.

    See Also
    --------
    other_func : Element-wise transformation used internally.
    DataHolder : Class for storing computation results.

    References
    ----------
    .. [1] Smith et al. (2020). "Advanced Data Processing
       Techniques." Journal of Computation, 15(3), 42-58.

    Examples
    --------
    Basic usage with default mode:

    >>> result = mega_function([1.0, 2.0, 3.0])
    >>> result["mode"]
    'default'
    >>> result["count"]
    3

    Using strict mode with a threshold:

    >>> result = mega_function([0.1, 0.6, 0.9], mode="strict", threshold=0.5)
    >>> result["filtered"]
    [0.6, 0.9]

    The transformation uses :py:func:`other_func` internally:

    >>> result = mega_function([4.0])
    >>> result["result"]
    2.0
    """
    if not data:
        raise ValueError("data must not be empty")
    if mode not in ("default", "strict"):
        raise ValueError(f"Unknown mode: {mode}")

    if mode == "strict":
        filtered = [x for x in data if x >= threshold]
    else:
        filtered = list(data)

    transformed = [other_func(x) for x in filtered]
    result_value = sum(transformed) / len(transformed) if transformed else 0.0

    return {
        "result": result_value,
        "filtered": filtered,
        "mode": mode,
        "count": len(filtered),
    }


def other_func(x: float) -> float:
    """Apply a square-root transformation to a single value.

    Parameters
    ----------
    x : float
        A numeric value to transform.

    Returns
    -------
    float
        The square root of the absolute value of ``x``.

    See Also
    --------
    mega_function : Main function that uses this transformation.

    Examples
    --------
    >>> other_func(4.0)
    2.0

    >>> other_func(0.0)
    0.0
    """
    import math
    return math.sqrt(abs(x))


class DataHolder:
    """A container for holding computation results.

    Parameters
    ----------
    name : str
        The name of the data holder.

    Examples
    --------
    >>> dh = DataHolder("results")
    >>> dh.get_data()
    {}
    """

    def __init__(self, name: str):
        """Initialize the DataHolder.

        Parameters
        ----------
        name : str
            The name of the data holder.
        """
        self.name = name
        self._data: dict = {}

    def get_data(self) -> dict:
        """Return the stored data.

        Returns
        -------
        dict
            The stored data dictionary.

        Examples
        --------
        >>> dh = DataHolder("test")
        >>> dh.get_data()
        {}
        """
        return self._data

📄 README.md

# gdtest-stress-all-docstr

Stress test with every docstring feature.

📄 great-docs.yml generated

# Great Docs Configuration
# See https://posit-dev.github.io/great-docs/user-guide/configuration.html

# Module Name (optional)
# ----------------------
# Set this if your importable module name differs from the project name.
# Example: project 'py-yaml12' with module name 'yaml12'
# module: yaml12

# Docstring Parser
# ----------------
# The docstring format used in your package (numpy, google, or sphinx)
parser: numpy

# Dynamic Introspection
# ---------------------
# Use runtime introspection for more accurate documentation (default: true)
# Set to false if your package has cyclic alias issues (e.g., PyO3/Rust bindings)
dynamic: true

# API Discovery Settings
# ----------------------
# Exclude items from auto-documentation
# exclude:
#   - InternalClass
#   - helper_function

# Logo & Favicon
# ---------------
# Point to a single logo file (replaces the text title in the navbar):
# logo: assets/logo.svg
#
# For light/dark variants:
# logo:
#   light: assets/logo-light.svg
#   dark: assets/logo-dark.svg
#
# To show the text title alongside the logo, add: show_title: true

# Funding / Copyright Holder
# --------------------------
# Credit the organization that funds or holds copyright for this package.
# Displays in sidebar and footer. Homepage and ROR provide links.
# funding:
#   name: "Posit Software, PBC"
#   roles:
#     - Copyright holder
#     - funder
#   homepage: https://posit.co
#   ror: https://ror.org/03wc8by49

# API Reference Structure
# -----------------------
# Customize the sections below to organize your API documentation.
# - Reorder items within a section to change their display order
# - Move items between sections or create new sections
# - Use 'members: false' to exclude methods from documentation
# - Add 'desc:' to sections for descriptions

reference:
  - title: Classes
    desc: Main classes provided by the package
    contents:
      - DataHolder  # 1 method(s)

  - title: Functions
    desc: Utility functions
    contents:
      - mega_function
      - other_func

# Site URL
# --------
# Canonical address of the deployed documentation site.
# Required for subdirectory deployments, skills page install commands,
# .well-known/ discovery, and sitemaps.
# site_url: "https://your-org.github.io/your-package/"

# Site Settings
# -------------
# site:
#   theme: flatly              # Quarto theme (default: flatly)
#   toc: true                  # Show table of contents (default: true)
#   toc-depth: 2               # TOC heading depth (default: 2)
#   toc-title: On this page    # TOC title (default: "On this page")

# Jupyter Kernel
# --------------
# Jupyter kernel to use for executing code cells in .qmd files.
# This is set at the project level so it applies to all pages, including
# auto-generated API reference pages. Can be overridden in individual .qmd
# file frontmatter if needed for special cases.
jupyter: python3

# CLI Documentation
# -----------------
# cli:
#   enabled: true              # Enable CLI documentation
#   module: my_package.cli     # Module containing Click commands
#   name: cli                  # Name of the Click command object