Overhaul documentation and modernise tqdm usage

[bjmorgan]

Summary

• Comprehensive documentation rewrite: narrative getting-started guide, core-concepts page, and four focused guides (recipes, symmetry measures, neighbour analysis, trajectories) replace the old auto-generated module stubs and unlinked example notebooks.
• Grouped single-page API reference with ~30 newly filled docstrings across the codebase.
• Modernised Sphinx configuration: myst-parser replaces deprecated recommonmark, added intersphinx cross-references to pymatgen/numpy/scipy/matplotlib, type hints rendered in descriptions.
• Switched from tqdm/tqdm.notebook to tqdm.auto for automatic terminal/Jupyter detection. The progress parameter on Trajectory.from_structures(), from_xdatcar(), and from_xdatcars() is now bool only ("notebook" option removed) with a runtime TypeError guard — breaking change.
• Fixed Trajectory.extend(): now extends both structures and configurations (previously only configurations), and removed dead offset parameter.
• Renamed SymmetryMeasure.string to SymmetryMeasure.name.
• Standardised (verbose, ncores, progress) parameter ordering across all Trajectory factory methods.
• Version bumped to 0.6.0.

[Copilot]

Pull request overview

Modernizes the documentation site and progress-bar handling, while aligning public APIs with the new tqdm.auto approach and updating versioning to reflect breaking changes.

Changes:

• Replaced legacy Sphinx stub pages/notebook-driven docs with narrative guides + a grouped single-page API reference.
• Migrated progress bars from tqdm / tqdm.notebook to tqdm.auto and removed the progress="notebook" option (bool-only).
• Renamed SymmetryMeasure.string to SymmetryMeasure.name, fixed Trajectory.extend() structure/config sync, and bumped version to 0.6.0.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_trajectory.py	Adds regression coverage ensuring extend() keeps structures/configurations in sync.
tests/test_symmetry_measure.py	Updates tests for SymmetryMeasure.name rename.
pyproject.toml	Bumps project version to 0.6.0.
polyhedral_analysis/utils.py	Replaces placeholder docstring for prune_neighbour_list() with real documentation.
polyhedral_analysis/trajectory.py	Switches to tqdm.auto, removes string-based progress mode, fixes extend() sync, updates docstrings/API.
polyhedral_analysis/symmetry_measure.py	Renames string → name, adds/expands docstrings.
polyhedral_analysis/rotation_analyser.py	Improves docstring formatting for mathematical expressions.
polyhedral_analysis/polyhedra_recipe.py	Adds docstrings to recipe helpers and polyhedra construction functions.
polyhedral_analysis/orientation_parameters.py	Adds docstring for projection_xyz().
polyhedral_analysis/octahedral_analysis.py	Fixes docstring markup formatting.
polyhedral_analysis/csm.py	Streamlines SymmetryMeasureResult docs using field comments.
polyhedral_analysis/coordination_polyhedron.py	Adds extensive docstrings across core API/properties.
docs/source/reference/citing.rst	Adds citation guidance page.
docs/source/reference/changelog.rst	Adds changelog page including CHANGELOG.md.
docs/source/reference/api.rst	Adds grouped API reference page.
docs/source/polyhedral_analysis.utils.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.trajectory.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.symmetry_measure.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.rst	Removes old package index stub page.
docs/source/polyhedral_analysis.rotation_analyser.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.polyhedron_trajectory.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.polyhedra_recipe.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.orientation_parameters.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.octahedral_analysis.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.coordination_polyhedron.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.configuration.rst	Removes old auto-generated module stub page.
docs/source/polyhedral_analysis.atom.rst	Removes old auto-generated module stub page.
docs/source/modules.rst	Removes old modules toctree entrypoint.
docs/source/index.rst	Replaces default index with narrative landing page and new toctree structure.
docs/source/guides/trajectories.rst	Adds trajectory guide (loading/progress/parallelism/combining).
docs/source/guides/symmetry-measures.rst	Adds continuous symmetry measures guide.
docs/source/guides/recipes.rst	Adds recipe definition guide with examples.
docs/source/guides/neighbour-analysis.rst	Adds neighbour analysis guide.
docs/source/getting-started.rst	Adds installation + quick start guide.
docs/source/core-concepts.rst	Adds core concepts overview and class relationships.
docs/source/conf.py	Modernizes Sphinx config (myst-parser, intersphinx, typehints in description).
docs/source/_static/config_0000.poscar	Adds static example POSCAR used in documentation/examples.
docs/requirements.txt	Updates doc build dependencies (drops recommonmark/nbsphinx, adds myst-parser, bumps Sphinx).
CHANGELOG.md	Documents 0.6.0 breaking changes/bug fixes/docs overhaul.

Comments suppressed due to low confidence (2)

polyhedral_analysis/trajectory.py:126

• Trajectory.__add__ returns a new Trajectory but reuses the same Structure/Configuration objects (shallow concatenation). This is inconsistent with extend(), which deep-copies configurations to avoid shared mutable state, and can lead to surprising aliasing when mutating configurations in the summed trajectory. Consider deep-copying here as well, or explicitly documenting that + is a shallow concat.
  polyhedral_analysis/trajectory.py:38
• Trajectory.__init__ doesn’t validate that structures and configurations have the same length. Since the class assumes 1:1 correspondence (and __len__ is based on structures), mismatched inputs can silently create out-of-sync trajectories. Consider raising ValueError when len(structures) != len(configurations).

---

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