api-docs/chemistry: add Doxygen documentation to chemistry and restraints headers - #420
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>
Add comprehensive /// comments to all public enums, structs, nested types, and functions in chemcomp.hpp, including: - BondType and ChiralityType enums with value descriptions - Restraints struct with nested AtomId, Bond, Angle, Torsion, Chirality, Plane types - All Restraints methods for finding and managing bond, angle, torsion, chirality, and planarity restraints - ChemComp struct with Group enum, Atom and Aliasing nested types - ChemComp atom lookup and manipulation methods - Standalone utility functions for bond/chirality type conversion - make_chemcomp_from_block CIF parser All documentation follows Doxygen conventions with @brief, @PARAM, @return, @tparam, @throws tags as appropriate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Enhance /// comments for the two main functions: - generate_chemcomp_xyz_from_restraints: Detailed description of idealized coordinate generation from bond/angle/torsion restraints - refine_chemcomp_xyz: Levenberg-Marquardt refinement against restraints Add @brief, @PARAM, @return tags with parameter descriptions and implementation notes about coordinate initialization and optimization. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- find_shortest_path @return: path goes from a to b, not b to a - get_from const overload: rename alt2 -> altloc2 to match non-const signature Co-authored-by: C. Vonrhein / CV-GPhL
Add comprehensive Doxygen documentation for EnerLib struct and its nested components including RadiusType enum, Atom and Bond structs, along with free function operators. Follows Gemmi documentation standards. Co-authored-by: C. Vonrhein / CV-GPhL
Add comprehensive Doxygen documentation for MonLib, ChemLink, ChemMod structs and all their nested types, along with free functions. Document all data members, methods, and parameters. Mark deprecated read_monomer_lib free function with @deprecated tag. Follows Gemmi documentation standards. Co-authored-by: C. Vonrhein / CV-GPhL
Add comprehensive Doxygen triple-slash comments documenting: - HydrogenChange enum with all 6 enumerators - Topo struct and internal pointer constraints - Bond, Angle, Torsion, Chirality, and Plane restraint structs - RKind enum and Rule struct - Link and Mod structs with all members - FinalChemComp and ResInfo structs - ChainInfo struct with group_end() method - has_atom() template - All Topo data members and indices - Helper methods (find_resinfo, take_bond, take_angle, etc.) - Public methods with @note for pointer stability constraints - Free functions (prepare_topology, make_chemcomp_with_restraints, find_missing_atoms) Co-authored-by: C. Vonrhein / CV-GPhL
Co-authored-by: C. Vonrhein / CV-GPhL
Co-authored-by: C. Vonrhein / CV-GPhL
Co-authored-by: C. Vonrhein / CV-GPhL
Co-authored-by: C. Vonrhein / CV-GPhL
Registers all 9 headers documented in api-docs/chemistry: chemcomp.hpp, chemcomp_xyz.hpp, ener_lib.hpp, monlib.hpp, topo.hpp, riding_h.hpp, linkhunt.hpp, to_chemcomp.hpp, mmcif_impl.hpp. Co-authored-by: C. Vonrhein / CV-GPhL
conf.py runs Doxygen when available (which it is on VS2022 workers) and conditionally loads breathe when the XML output dir exists. Without breathe installed, the Sphinx build fails with an ImportError. 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
Adds Doxygen
///triple-slash API documentation to 9 headers coveringchemical components, the monomer library, restraint topology, hydrogen
placement, link hunting, and related I/O helpers.
Headers documented:
chemcomp.hppchemcomp_xyz.hppener_lib.hppmonlib.hpptopo.hppriding_h.hpplinkhunt.hppto_chemcomp.hppmmcif_impl.hppdocs/api.rst: new Chemistry and Restraints section registers all 9 headers.
Part of the incremental API documentation series (#413 – #419 preceding PRs).
Test plan
🤖 Generated with Claude Code