gdtest_mixed_docs — Synthetic Package Details

#005 gdtest_mixed_docs OK INIT

Mixed docstring styles (NumPy + Google); transform is %nodoc and should not appear

Five exports (Converter class, encode, decode, validate, transform) mixing NumPy and Google docstrings in the same module. On the Reference page you should see 'Classes' and 'Functions' sections. Both docstring styles should be rendered cleanly — NumPy Parameters tables and Google Args sections should both appear correctly.

View Site → Build Log 🧪 Test Coverage

Build Mode

○ No great-docs.yml

This package has no pre-supplied config. It tests the full great-docs init → great-docs build pipeline from scratch, relying entirely on auto-detection of the package layout, docstring style, and exports.

Dimensions

A1 B1 C4 D5 E6 F6 G1 H7

A1Flat layoutlayout

B1Explicit __all__exports

C4Mixed class+funcobjects

D5Mixed stylesdocstrings

E6No directivesdirectives

F6No user guideuser_guide

G1README.mdlanding

H7No extrasextras

Source Files

📁 gdtest_mixed_docs/

📄 __init__.py

"""A package with mixed NumPy and Google docstrings."""

__version__ = "0.1.0"
__all__ = ["Converter", "encode", "decode", "validate", "transform"]


class Converter:
    """
    A data converter.

    Parameters
    ----------
    fmt
        The output format.
    """

    def __init__(self, fmt: str = "json"):
        self.fmt = fmt

    def convert(self, data: str) -> str:
        """
        Convert data to the target format.

        Parameters
        ----------
        data
            The input data string.

        Returns
        -------
        str
            Converted data.
        """
        return data


def encode(data: str, encoding: str = "utf-8") -> bytes:
    """
    Encode a string to bytes.

    Parameters
    ----------
    data
        The string to encode.
    encoding
        The target encoding.

    Returns
    -------
    bytes
        The encoded bytes.
    """
    return data.encode(encoding)


def decode(data: bytes, encoding: str = "utf-8") -> str:
    """
    Decode bytes to a string.

    Parameters
    ----------
    data
        The bytes to decode.
    encoding
        The source encoding.

    Returns
    -------
    str
        The decoded string.
    """
    return data.decode(encoding)


def validate(data: str) -> bool:
    """Validate the input data.

    Args:
        data: The data string to validate.

    Returns:
        True if the data is valid.
    """
    return len(data) > 0


def transform(data: str, upper: bool = False) -> str:
    """Transform the input data.

    %nodoc

    Args:
        data: The data string to transform.
        upper: If True, convert to uppercase.

    Returns:
        The transformed data string.
    """
    return data.upper() if upper else data

📄 README.md

# gdtest-mixed-docs

A synthetic test package with mixed NumPy and Google docstrings.

📄 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:
      - Converter  # 1 method(s)

  - title: Functions
    desc: Utility functions
    contents:
      - decode
      - encode
      - transform
      - validate

# 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