Docs: replace xyz files with xyz strings

[eimrek]

This PR replaces the .xyz file loading with directly embedded xyz string in documentation examples.

Motivated by the fact that it's not easy to find these structure for users following the documentation. xyz string allow to directly copy-paste the blocks and test out the code on your own.

[Copilot]

Pull request overview

This PR updates the documentation example snippets to embed molecular geometries directly as XYZ-formatted strings (instead of loading .xyz files from the docs tree), making the examples copy/paste runnable without needing to locate auxiliary data files.

Changes:

• Replaced Structure.from_xyz_file(...) usage with Structure.from_xyz(...) across Python documentation examples.
• Replaced Structure::from_xyz_file(...) usage with Structure::from_xyz(...) across C++ documentation examples.
• Removed no-longer-referenced .xyz data files from docs/source/_static/examples/data/.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/source/_static/examples/python/scf_solver.py	Embed H2 geometry as inline XYZ string.
docs/source/_static/examples/python/release_notes_v1_1.py	Embed H2 geometry inline for release notes snippets.
docs/source/_static/examples/python/quickstart.py	Embed para-benzyne geometry inline for quickstart.
docs/source/_static/examples/python/qubit_mapper.py	Embed water geometry inline for mapping example.
docs/source/_static/examples/python/orbitals.py	Embed H2 geometry inline for orbitals example.
docs/source/_static/examples/python/mcscf.py	Embed stretched N2 geometry inline for MCSCF example.
docs/source/_static/examples/python/mc_calculator.py	Embed H2 geometry inline for MC calculator example.
docs/source/_static/examples/python/localizer.py	Embed water geometry inline for localization example.
docs/source/_static/examples/python/interfaces.py	Embed H2 geometry inline for interfaces example.
docs/source/_static/examples/python/hamiltonian.py	Embed water geometry inline for Hamiltonian example.
docs/source/_static/examples/python/hamiltonian_constructor.py	Embed H2 geometry inline for constructor example.
docs/source/_static/examples/python/factory_pattern.py	Embed H2 geometry inline for factory-pattern example.
docs/source/_static/examples/python/dynamical_correlation.py	Embed H2 geometry inline for correlation example.
docs/source/_static/examples/python/design_principles.py	Embed H2 geometry inline for design principles example.
docs/source/_static/examples/python/ansatz.py	Embed H2 geometry inline for ansatz example.
docs/source/_static/examples/python/active_space_selector.py	Embed water geometry inline for active-space selection example.
docs/source/_static/examples/data/para_benzyne.structure.xyz	Removed (example no longer depends on external XYZ file).
docs/source/_static/examples/data/n2_stretched.structure.xyz	Removed (example no longer depends on external XYZ file).
docs/source/_static/examples/cpp/scf_solver.cpp	Use inline XYZ string for H2 structure.
docs/source/_static/examples/cpp/quickstart.cpp	Use inline XYZ string for para-benzyne structure.
docs/source/_static/examples/cpp/orbitals.cpp	Use inline XYZ string for H2 structure.
docs/source/_static/examples/cpp/localizer.cpp	Use inline XYZ string for water structure.
docs/source/_static/examples/cpp/hamiltonian.cpp	Use inline XYZ string for water structure.
docs/source/_static/examples/cpp/hamiltonian_constructor.cpp	Use inline XYZ string for H2 structure.
docs/source/_static/examples/cpp/dynamical_correlation.cpp	Use inline XYZ string for H2 structure.
docs/source/_static/examples/cpp/ansatz.cpp	Use inline XYZ string for H2 structure.
docs/source/_static/examples/cpp/active_space_selector.cpp	Use inline XYZ string for water structure.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[eimrek]

@ConradJohnston I saw #252. happy to discuss

[ConradJohnston]

Hi @eimrek,

Do you want to try rendering the xyzs from file at doc build time?
The single-source of truth provided by the files was nice to prevent xyzs getting scrambled in-line.

[eimrek]

@ConradJohnston @wavefunction91

i'm not sure about this.

Do we want:

Option 1

Dynamical conversion of

structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz")

into

structure = Structure.from_xyz("""2
H2 molecule
H    0.000000    0.000000    0.000000
H    0.000000    0.000000    0.740848
""")

Option 2

Have a separate styled box in the docs that contains the file contents before each example where a file is loaded.

This seems quite involved, and still users need to copy-paste the file and update the path to run the example - maybe not as seamless as option 1.

[ConradJohnston]

Hi @eimrek,

Yes, option 1, please.

Convert to string at doc build time so that we have a fully runnable snippet in the docs, but that comes from a single version-controlled file that is re-usable everywhere.

You of course don't need qdk-chemistry - just write a script to do some string formatting,
You can then add this conversion script as a target to the docs' Makefile and have it modify the docs source files to include the explicit coordinates.

[ConradJohnston]

Please look at keeping the XYZ files, but populating the docs at compile time via string conversion.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 1 comment.

[eimrek]

@ConradJohnston Thanks for the suggestion, yes, I think this approach is great.

I added a sphinx custom extension that embeds the xyz if you write # docs:inline-xyz marker on from_xyz_file.

E.g.

structure = Structure.from_xyz_file(path)  # docs:inline-xyz

Per the principle of least surprise, i went for the opt-in version rather than opt-out (opt-out would be to convert all by default and skip conversion for cases w a marker).

[wavefunction91]

@eimrek can you include a screenshot of the generated docs resulting from this?

[eimrek]

Here's what is looks like at the moment.

Note the unused path import at the beginning of the file.

Another point is that we test the original file, not the converted file. The conversion itself is simple and shouldn't have problems but still it's not tested.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 27 comments.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 27 comments.

[eimrek]

Alright, so now the XYZ string is inlined to all examples, and the original files are also kept as ground truth.

I added a test file: test_docs_xyz_consistency.py, which checks that if an example script's cell has the comment # docs:xyz file.xyz , then it expects a Structure.from_xyz call with same contents as the specified file.

E.g.

################################################################################
# docs:xyz ../data/h2.structure.xyz
# start-cell-create
from qdk_chemistry.data import Ansatz, Structure
from qdk_chemistry.algorithms import create

# Load H2 molecule structure from XYZ file
structure = Structure.from_xyz("""\
2
H2 molecule
H    0.000000    0.000000    0.000000
H    0.000000    0.000000    0.740848
""")
...

I added these checks to all tests where relevant, but note that it's opt-in at the moment - so you could also skip the # docs:xyz comment and everything would work as expected.

However, @mmoerchen mentioned that it might make sense to mandate that in every example we do Structure.from_xyz, there should be corresponding # docs:xyz comment (with a potential option to explicitly opt-out of the check). Happy to implement this if we're sure we want it now, but this check could also be added some time in the future.

@wavefunction91

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.