# Review of the moldenViz documentation and recommendations for improvement

## Overview of the current documentation
moldenViz is a Python package for parsing Molden files (a format used by many quantum‑chemistry programs), tabulating Gaussian‑type orbitals and molecular orbitals, and displaying them interactively.  Versions up to 0.3.x offered only a minimal API reference; there was almost no narrative documentation.  By version 1.0.0 (September 2025), the documentation on Read‑the‑Docs has been expanded to include a user guide with installation instructions, command‑line usage, Python examples, configuration reference and troubleshooting sections.  The main sections of the latest docs are:
- Getting started – describes installation and verifying that tkinter is available.
- Command‑line guide – explains how to render a molecule (moldenViz path/to/file.molden), how to show only molecular structure (‑m flag) and lists example molecules included with the package.
- Python API guide – explains how to parse a Molden file (Parser class), plot molecules (Plotter), use bundled examples, tabulate orbitals (Tabulator), supply custom grids and inspect parsed data.
- Configuration reference – describes how to override default settings with a ~/.config/moldenViz/config.toml file and lists default values for grids, molecular orbital isosurfaces and atom/bond rendering; it also provides examples for tuning bonds, grid resolution, orbital contour and per‑element colours.
- Troubleshooting – shows how to handle missing files, invalid Molden formats and errors that arise when creating grids with only_molecule=True.

This user guide is complemented by a generated API reference for the Parser, Tabulator and Plotter classes.  The API reference lists function signatures and brief docstrings but does not provide usage examples.  The GitHub README also contains valuable information on installation, CLI usage, Python examples and the roadmap; for instance, it explains how to install tkinter, shows how to run the CLI (moldenViz molden.inp or moldenViz -e co) and demonstrates the Plotter and Tabulator classes inside Python.  However, much of this information is absent from earlier versions of the online documentation; for example, the Usage page in the 0.3.0 and 0.3.5 docs merely states “refer to the GitHub page” and provides no examples.

Strengths of the current documentation
- Comprehensive configuration reference – the 1.0.0 docs provide a complete listing of default settings and instructions for creating a configuration file.  Users can see the default grid sizes, contour levels and atom/bond properties and override them.
- Clear separation between CLI and Python API – the guides differentiate how to run moldenViz from the command line versus using it within Python scripts.  Examples show both quick invocations (moldenViz -e benzene) and programmatic use (Plotter('molden.inp')).
- Introductory explanation of prerequisites – the Getting Started page explains the need for tkinter and how to verify or install it on different platforms.
- Troubleshooting section – the docs proactively address common problems such as missing files, invalid Molden formats and configuration errors, offering Python snippets that catch and report these exceptions.

Key gaps and limitations in the documentation
1. Minimal high‑level explanation of the Molden format and limitations.  The docs assume readers already know what a Molden file is.  There is no explanation of the file format, the meaning of the [Atoms], [GTO] and [MO] sections or which quantum‑chemistry programs can output Molden files.  The parser currently only supports spherical Gaussian functions; the code raises an error when cartesian functions (5D or 9G) appear, yet this limitation is mentioned only in a code comment rather than in the user guide.
2. No diagrams or screenshots.  The documentation does not show what the interactive plot window looks like, what the orbital selection interface contains or how different configuration settings affect the rendered molecule.  Screenshots and annotated images would help users understand the visual output and the effect of configuration options.
3. Sparse CLI documentation.  The CLI guide lists only the basic commands and example names.  It does not enumerate all available flags and options (e.g., output image export, resolution settings or configuration overrides).  Users must run moldenViz -h to discover other flags; the documentation should instead summarise them in a table.
4. Insufficient explanation of advanced Python workflows.  The Python API guide provides minimal examples for parsing, plotting and tabulating.  It does not explain the interplay between Parser, Tabulator and Plotter, nor does it describe how to customise the PyVista viewer (e.g., rotation, colourmaps) or handle headless environments.  There is no guidance on performance considerations, such as the memory footprint of large grids or how grid resolution affects plotting speed.
5. Missing configuration examples for atoms and bonds.  While the configuration reference lists the available keys, it lacks examples demonstrating how to set per‑atom radii, adjust bond colouring or reduce bond radius for large molecules.  Users might not realise they can override element‑specific colours or maximum bond counts until they read the raw TOML snippet.
6. No mention of dependencies or environment requirements beyond tkinter.  The docs do not list the specific versions of Python, NumPy, SciPy, PyVista or PyVistaQt required.  They do not instruct users how to install these dependencies on systems without GPU support or how to run the package in headless mode (e.g., inside Jupyter notebooks or on a remote server).
7. Lack of guidelines for citing or acknowledging the software.  Many academic users will need to cite moldenViz or the underlying libraries.  The documentation does not provide citation guidelines or references to the original molden specification or the scientific papers that justify the mathematical formulas (e.g., normalisation of Gaussian functions).  The code comments refer to Jiyun Kuang and C D Lin’s 1997 paper, but these references are not surfaced in the user documentation.
8. Version confusion and outdated pages.  The v0.3.x documentation remains on Read‑the‑Docs but contains no content in the Usage page.  Users searching for the package might land on these old pages and assume the project is poorly documented.  The README file includes useful information not mirrored in earlier docs, such as example molecules and configuration hints.
9. No contribution guidelines or roadmap discussion.  Although the GitHub README lists a roadmap with planned features and completed milestones, the documentation site does not mention these plans or provide guidance on how to contribute to the project.

## Recommendations for improvement
### Consolidate and reorganise documentation
- Redirect or remove outdated versions.  Configure Read‑the‑Docs to redirect the v0.3.x Usage page to the latest version or add a banner indicating that the page is outdated.  This will prevent confusion for users who see the empty Usage page.
- Integrate README content into the Getting Started guide.  The README contains crucial information on installation, tkinter setup, CLI usage and example molecules.  Incorporate these details into the Getting Started and CLI sections of the documentation rather than referring users back to GitHub.
- Provide a high‑level overview of the Molden format.  Add a new section in the Getting Started or Python API guide explaining the structure of Molden files, the purpose of the [Atoms], [GTO] and [MO] sections and which quantum‑chemistry codes generate compatible outputs.  Explicitly state that the current parser supports only spherical Gaussian basis functions and does not support Cartesian orbitals (e.g., 5D/9G), which are rejected during parsing.
- Add a detailed CLI reference.  Create a table enumerating all command‑line options (flags for selecting orbitals, exporting images, disabling bonds, specifying configuration files, etc.), with descriptions and default values.  This reduces the need for users to run moldenViz ‑h to discover features.
- Enhance the API reference with examples.  For each class and key method in the Parser, Tabulator and Plotter APIs, include code snippets demonstrating typical usage.  For instance, show how to create a Cartesian grid with custom resolution and tabulate a set of orbitals, then pass the same Tabulator to a Plotter.  Explain performance considerations (e.g., large grids may consume significant RAM) and how to choose between spherical and Cartesian grids.
- Document configuration options comprehensively.  Build upon the configuration reference by adding narrative explanations and examples.  For example:
- Show how to customise bond colours and radii to emphasise specific bonds, with before/after screenshots.
- Explain the difference between color_type='uniform' and color_type='split' for bonds.
- Provide examples of per‑atom overrides using Atom.<atomic number> tables to change colour and radius.
- Describe how the min_radius and max_radius_multiplier settings influence the default spherical grid and how increasing num_r_points or num_x_points affects the resolution and computational cost.
- Show how to adjust molecular orbital contour levels and opacities in the configuration and illustrate how these changes affect the visualisation.

### Include visuals and interactive demonstrations
- Screenshots of the GUI and interactive controls.  Add annotated images showing the PyVista viewer, the Tkinter orbital selection window, and the effect of toggling the molecule visibility or adjusting contour levels.  Visuals can accompany each major section (CLI, Python API, configuration reference) to orient new users.
- Demonstrate configuration effects.  Provide side‑by‑side images of a molecule rendered with default settings versus with customised colours, bond radii and orbital contour levels.  This will help users understand the purpose of each configuration key.
- Embed short videos or GIFs.  For features such as rotating the molecule, selecting orbitals, and changing isosurface levels, consider embedding short animations (hosted on an external platform if necessary) to show the interactivity of the application.

### Expand guidance for advanced workflows and performance
- Explain how to handle large systems.  Provide guidelines on selecting appropriate grid resolutions and memory considerations when dealing with large molecules or high numbers of molecular orbitals.  Discuss how to sample only a subset of orbitals to reduce computation.
- Headless or remote visualisation.  Document whether moldenViz can be used in headless environments (e.g., HPC clusters or remote servers without a display).  If not currently supported, provide instructions for exporting the grid and using external tools (such as VMD or PyVista offline rendering) to generate static images.
- Extend Tabulator to support custom grids.  The current implementation restricts the grid type to spherical or Cartesian and raises an error otherwise.  Consider adding support for custom grids (e.g., radial grids with non‑uniform spacing or adaptive grids) and document how to use them.
- Clarify how to supply pre‑computed grid data.  The advanced workflow section touches on passing a Tabulator with a custom grid to Plotter, but it does not show how to share grid data between multiple calculations or how to reuse a grid for different molecules.  Provide guidelines on serialising grid and orbital data for reuse.
- Document error handling and exceptions.  Beyond the Troubleshooting page, include a comprehensive list of potential exceptions thrown by the parser, tabulator and plotter (e.g., invalid shell labels, unsupported basis functions, out‑of‑bounds orbital indices).  Explain how to catch these errors and suggest corrective actions.

### Provide academic context and citation guidelines
- Explain the theoretical background.  Include a short appendix or link to external resources explaining how Gaussian‑type orbitals are normalised (referencing the formulas in Kuang & Lin 1997), how molecular orbitals are constructed, and how the radial/angular functions are tabulated.  This will help users verify the correctness of the computations and understand the physical meaning of the visualisations.
- Offer citation guidance.  Many researchers will need to cite moldenViz when using it in publications.  Provide a suggested citation, including the software version and DOI (if available), along with instructions on how to cite the underlying libraries (PyVista, SciPy, etc.) and the original Molden format specification.

### Encourage contributions and community involvement
- Add a “Contributing” section.  Describe how users can contribute bug reports, feature requests or code contributions.  Provide a link to the GitHub repository and instruct potential contributors on how to run tests and build the documentation locally.
- Maintain an updated roadmap.  Move the roadmap currently in the README to a “Roadmap” page in the documentation.  Include a changelog summarising major changes between versions and planned features (e.g., support for Cartesian basis functions or new visualisation features).  This helps users understand the project’s evolution and future direction.
- Gather and showcase user examples.  Encourage users to share screenshots or notebooks using moldenViz and host a gallery of interesting molecules and orbitals rendered with the tool.  Real‑world examples inspire new users and demonstrate the capabilities of the software.

## Conclusion
The 1.0.0 documentation for moldenViz represents a significant improvement over earlier versions, providing a structured user guide, configuration reference and troubleshooting section.  However, there remain several areas that could be enhanced.  The documentation should offer more context about the Molden format and the mathematical foundations of the visualisation, include comprehensive CLI and API references with examples, and provide visuals to demonstrate the tool’s capabilities.  Clearer guidance on advanced usage, performance considerations, citation, and community involvement will make the package more accessible to scientists and developers.  Implementing the recommendations outlined above will help users adopt moldenViz confidently and contribute to its growth.
