gdtest_bibliography — Synthetic Package Details

#308 gdtest_bibliography OK CONFIG

Project-level bibliography forwarded into _quarto.yml

A package whose great-docs.yml sets a single project-level `bibliography: docs/references.bib` key (issue #214) and then cites it from four different contexts with no per-page `bibliography:` frontmatter: the homepage (README→index.qmd), a top-level user-guide page, a user-guide page nested one subdirectory deep, and a function docstring on a generated API reference page. One key (knuth1984) is shared across pages to prove a single bibliography serves the whole project. Great Docs should copy the .bib into the build directory and write `bibliography: references.bib` into _quarto.yml, so Quarto's citeproc resolves every citation inline and renders a References section on each page — regardless of nesting depth. If the wiring is missing you'll see raw [@knuth1984] text and no references, exactly the bug this verifies is fixed.

View Site → Build Log 🧪 Test Coverage

Build Mode

● Has great-docs.yml

This package ships a pre-supplied config. The great-docs init step is skipped and great-docs build uses the spec-defined configuration directly. Tests specific config options and their rendered output.

Dimensions

A1 B1 C1 D1 E6 F1 G1 H7 K57

A1Flat layoutlayout

B1Explicit __all__exports

C1Functions onlyobjects

D1NumPydocstrings

E6No directivesdirectives

F1Auto-discoveruser_guide

G1README.mdlanding

H7No extrasextras

K57project-level bibliographyconfig

Source Files

📁 docs/

📄 references.bib

@article{knuth1984,
  title = {Literate Programming},
  author = {Knuth, Donald E.},
  year = {1984},
  journal = {The Computer Journal},
  volume = {27},
  number = {2},
  pages = {97--111},
}

@book{lamport1994,
  title = {LaTeX: A Document Preparation System},
  author = {Lamport, Leslie},
  year = {1994},
  publisher = {Addison-Wesley},
  edition = {2nd},
}

@article{parnas1972,
  title = {On the Criteria to Be Used in Decomposing Systems into Modules},
  author = {Parnas, David L.},
  year = {1972},
  journal = {Communications of the ACM},
  volume = {15},
  number = {12},
  pages = {1053--1058},
}

📁 gdtest_bibliography/

📄 __init__.py

"""Package demonstrating project-level citations."""

__version__ = "0.1.0"
__all__ = ["weave", "tangle"]


def weave(source: str) -> str:
    """
    Produce documentation from a literate source.

    The literate programming model this implements is due to Knuth
    [@knuth1984]; this docstring citation probes whether project-level
    bibliography resolution reaches generated API reference pages.

    Parameters
    ----------
    source
        The literate program source.

    Returns
    -------
    str
        The woven documentation.
    """
    return source


def tangle(source: str) -> str:
    """
    Extract compilable code from a literate source.

    Parameters
    ----------
    source
        The literate program source.

    Returns
    -------
    str
        The tangled code.
    """
    return source

📁 user_guide/

📁 02-advanced/

📄 01-decomposition.qmd

---
title: Modular Decomposition
---

Module boundaries should hide design decisions that are likely to
change [@parnas1972]. Combining that principle with literate
programming [@knuth1984] yields documentation that tracks the modular
structure of the code.

This page lives one directory deep under `user-guide/`, yet the same
project-level `bibliography:` key resolves its citations — no
depth-dependent per-page path is required.

This page deliberately adds *no* manual References heading: Quarto
generates the section automatically and titles it from the document
language (here, the English "References").

📄 01-citations.qmd

---
title: Citations
---

Literate programming was introduced by Knuth [@knuth1984], who argued
that programs should be written for human readers first. The approach
interleaves prose and code, and is often typeset with LaTeX
[@lamport1994].

These citations resolve project-wide because `great-docs.yml` sets a
single `bibliography:` key — no per-page frontmatter is needed.

## References

::: {#refs}
:::

📄 README.md

# gdtest-bibliography

Synthetic test for project-level `bibliography:` wiring (issue #214).
This package follows the literate programming tradition [@knuth1984].

## Purpose

A single `bibliography: docs/references.bib` entry in `great-docs.yml`
should:

- copy `references.bib` into the build directory, and
- set `bibliography: references.bib` in the generated `_quarto.yml`,

so that `[@citation-key]` syntax on *any* page resolves to a formatted
citation and a References section, with no per-page frontmatter.

## References

::: {#refs}
:::

📄 great-docs.yml

bibliography: docs/references.bib