docs: add Doxygen API documentation for calculations and analysis headers (PR 7/10)#419
Merged
Merged
Conversation
Wires up Doxygen XML generation + Breathe Sphinx extension so that C++ API documentation from header comments renders in the existing Sphinx/readthedocs site at docs/api.rst. - docs/Doxyfile: Doxygen config (XML-only output, internal headers excluded) - docs/conf.py: runs Doxygen as subprocess, adds breathe extension - docs/api.rst: stub C++ API reference page (expanded by subsequent PRs) - docs/index.rst: replace external cxx-api link with internal api.rst - docs/requirements.txt: add breathe >= 4.35 - .readthedocs.yaml: add apt_packages: [doxygen] - .gitignore: exclude docs/_doxygen/ (generated) Builds on prior work in project-gemmi#402 (Paul Emsley / pemsley). Co-authored-by: C. Vonrhein / CV-GPhL
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add comprehensive Doxygen documentation comments to all public items in the DSSP secondary structure assignment module: - All enum types and values (SecondaryStructure, TurnType, HelixPosition, BridgeType, HydrogenMode, HBondDefinition) - All public structs and their data members (Bridge, HBond, SecondaryStructureInfo, DsspOptions, DsspCalculator) - All public methods with @param, @return, and @brief tags - The calculate_dssp convenience function - Used @tparam and other tags as appropriate for clarity Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ons (PR 7) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3 tasks
sfcalc.hpp: Bourhis et al. (2015) for structure factor computation context. scaling.hpp: Afonine et al. (2012) for anisotropic scaling; Fokine/Urzhumtsev (2002) for initial bulk-solvent parameters. calculate.hpp: Merritt (2011) for B_est formula. dssp.hpp: Kabsch/Sander (1983) for DSSP algorithm. Co-authored-by: C. Vonrhein / CV-GPhL
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
2 participants
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
Seventh PR in the incremental Doxygen API documentation series. Adds
///doc comments to 12 headers covering calculations, analysis, and structure factor computation, and wires them intodocs/api.rstviadoxygenfile::directives.Headers documented:
Calculations and Analysis
calculate.hpp— geometric calculations (angles, dihedrals, Ramachandran, mass, B-factors, TLS)align.hpp— sequence alignment to SEQRES, label_seq_id assignment, QCP superpositionneighbor.hpp— cell-linked-list neighbour search (Model and SmallStructure)contact.hpp— distance-based contact search with configurable ignore rulesassembly.hpp— biological assembly generation, NCS expansion, chain namingselect.hpp— CCP4-style atom/residue/chain selection expressionsmodify.hpp— in-place structure modifications (remove H, altlocs, ANISOU; rename; deuterium handling)polyheur.hpp— polymer type heuristics, entity/subchain assignment, connectivity checksdssp.hpp— DSSP secondary structure assignment (helices, strands, turns, bends)Structure Factor Calculations
sfcalc.hpp— direct (non-FFT) structure factor summationecalc.hpp— amplitude normalisation F→E (Karle approach)scaling.hpp— anisotropic scaling with optional bulk-solvent correctionAlso includes the infrastructure changes from PR #413 (conf.py guard, Doxyfile, CI docs-build job) as they are not yet merged into master.
Literature references added
@par ReferencesDoxygen blocks added to cite primary sources in the rendered API docs:StructureFactorCalculatorinsfcalc.hppScalingstruct inscaling.hppcalculate_b_est()incalculate.hppDsspCalculatorindssp.hppDepends on
Part of the series starting with PR #413 (
api-docs/infra).Test plan
docs/api.rstrenders the two new sections without Breathe errors🤖 Generated with Claude Code