Repository navigation
DM-56680: Restructure the citations guide into an overview and recipes - #538
Open
jonathansick wants to merge 4 commits into
Open
jonathansick wants to merge 4 commits into
jonathansick wants to merge 4 commits into
Conversation
… undated check The undated-citation check exempted a URL-located software entry only when it was not reading a CITATION.cff preferred-citation, but it keyed that off the entry's cff_preferred flag, whose default *asks* for a preferred citation. A file that declares none hands the entry its top-level record, which describes the repository, and the entry was reported anyway. Documenteer's own CITATION.cff is such a file, and the docs build fails under -W without this fix. GuideCitation now carries cff_cited_preferred, the record the file actually supplied (CitationCffRecord.cited_preferred), alongside the cff_preferred flag the entry wrote. The exemption and the project-version fallback both follow the record read rather than the flag.
docs/guides/citations.rst was a single 655-line page that opened on the self/preferred distinction and CFF edge cases before showing a basic declaration. It is now a section, docs/guides/citations/, with an overview that starts from declaring an entry and where it shows up, recipes for specific kinds of site (DOI landing page, landing pages inside the site, CITATION.cff, never-deposited software, API-heavy sites), a page per display surface (cards, inline DOI links, footer, machine-readable metadata), and one troubleshooting page for every citation warning. Every label the TOML reference and the technote citations page link to moves with its section, and the old URL redirects to the overview. Documenteer's docs now declare real citations: a CITATION.cff at the repository root (software, no DOI, no version) as the preferred entry, and the ADASS XXXIII paper as a non-footer entry, so the cards, inline DOI links, and footer citation in these pages render live from the site's own configuration instead of being described in text.
Documentation preview
Build |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/guides/citations/): an overview that starts from declaring an entry and where it is displayed, recipes for specific kinds of site (DOI landing page, landing pages inside the site,CITATION.cff, never-deposited software, API-heavy sites), a page per display surface (cards, inline DOI links, footer, machine-readable metadata), and one troubleshooting page for every citation warning. Every label linked from the TOML reference and the technote citations page moves with its section, and the old URL redirects to the overview.CITATION.cffas the preferred Software entry and the ADASS XXXIII paper as a non-footer entry — so the cards,:doi:links, and footer citation in these pages render live from the site's configuration instead of being described in text.CITATION.cffthat declares nopreferred-citationwas reported as undated because the check keyed off thecff_preferredflag rather than the record actually read.GuideCitationnow carriescff_cited_preferred, and both the exemption and the project-version fallback follow it. Without this fix Documenteer's own entry fails the-Wdocs build.Validation steps
guides/citations/and confirm the overview shows the Software card (project version, link to documenteer.lsst.io, BibTeX keydocumenteer) and the Paper card (DOI link, key2025ASPC..541..151S), and that the footer's "How to cite" lists only Software.guides/citations/cards.html, confirm the three selector tabs (label, BibTeX key, DOI) render the same Paper card.citation_*meta tags in<head>, oneapplication/ld+jsonblock with aWebSitesubject and the software undercitation.guides/citations.htmlredirects toguides/citations/index.html.nox -s docs-linkcheck; the paper DOI reports as redirected (302 to aspbooks.org), not broken.References