gdtest-bibliography

Synthetic test for project-level bibliography: wiring (issue #214). This package follows the literate programming tradition (Knuth 1984).

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

Knuth, Donald E. 1984. “Literate Programming.” The Computer Journal 27 (2): 97–111.

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 (Knuth 1984) text and no references, exactly the bug this verifies is fixed.

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