Update Docs (#11)

* update docs

* docs

* update nodes

* add links to the soruce code

src/lib.rs

@@ -1,6 +1,26 @@
-//! This crate is for loading and serializing pymol's PSE filetype
+//! # PyMOL PSE Parser
 //!
-//! it is currently a work in progress.
+//! A Rust crate for working with PyMOL PSE (PyMOL Session) files.
+//!
+//! ## Features
+//!
+//! - Load and parse PSE files
+//! - Serialize PSE data
+//! - Access molecular structures and visualization settings
+//!
+//! ## Usage
+//!
+//! ```rust
+//! use pymolparsing::psedata::PSEData;
+//! let pse_data = PSEData::load("path/to/file.pse");
+//! // Work with the loaded PSE data
+//! psedata.to_disk_full("my_output_directory");
+//! ```
+//!
+//! ## Modules
+//!
+//! - `molviewspec`: Handles molecular viewing specifications
+//! - `pymolparsing`: Core parsing functionality for PSE files
 //!
 pub mod molviewspec;
 pub mod pymolparsing;

src/molviewspec/nodes.rs

@@ -1,9 +1,31 @@
+//! This module has functionality to build up MolViewSpec.
+//!
+//! MolViewSpec (MVS) is a lightweight, JSON-based specification for describing molecular structures and their visual representation.
+//! It is designed to be human-readable, easily shareable, and compatible with various molecular visualization tools.
+//!
+//! - MolViewSpec GitHub repository: https://github.com/molstar/mol-view-spec
+//! - MolViewSpec documentation: https://molstar.org/viewer/molviewspec/
+//! - MolStar Viewer (which supports MVS): https://molstar.org/viewer/
+//!
+//! We try to adhere very closely to the python library API. Almost all of the action happens
+//! on the `Nodes`. Because we are building a nested tree of data, we need most of the parts to
+//! be mutable and you can see almost all of the function calls:
+//!
+//! 1. check the type and the params and act only on correct parent nodes
+//! 2. beacuse of 1, we return `Option<>`
+//! 3. If a node is returned is it `&mut Node`
+//!
+//!
 use chrono::Utc;
 use serde::{Deserialize, Serialize};
 use serde_json;
 use urlencoding;
 use validator::Validate;
 
+// KindT
+//
+// Enum of node types corresponding to the MolViewSpec Nodes
+//
 #[derive(PartialEq, Serialize, Deserialize, Debug, Default, Clone)]
 #[serde(rename_all = "snake_case")]
 pub enum KindT {
@@ -34,6 +56,10 @@ pub enum KindT {
     Transform,
 }
 
+// NodeParams
+//
+// Enum of params per node type. Each of the variants are typed.
+//
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(untagged)]
 pub enum NodeParams {
@@ -68,6 +94,7 @@ pub enum NodeParams {
 /// This is the core datastructure for generating MSVJ files. Each node type can have a type, params, and children.
 ///
 /// Methods derived from the Python API found [here](https://github.com/molstar/mol-view-spec/blob/master/molviewspec/molviewspec/builder.py)
+///
 #[derive(Serialize, Deserialize, Debug, Default, Clone)]
 pub struct Node {
     pub kind: KindT,
@@ -317,6 +344,11 @@ pub enum DescriptionFormatT {
     Plaintext,
 }
 
+/// Metadata
+///
+/// The molviewspec metadata. High level info unrelated to
+/// structure visualization.
+///
 #[derive(Serialize, Deserialize, Debug, Default)]
 pub struct Metadata {
     pub version: String,
@@ -329,6 +361,11 @@ pub struct Metadata {
     pub timestamp: String,
 }
 
+/// This is the base MolViewSpec object containing
+/// the root node and the metadata
+///
+/// Holds methods that modify the root node.
+///
 #[derive(Serialize, Deserialize, Debug)]
 pub struct State {
     pub root: Node,
@@ -370,7 +407,6 @@ impl State {
     pub fn generic_visuals() {
         unimplemented!()
     }
-
     pub fn to_url(&self) -> String {
         let json = serde_json::to_string(&self).expect("Json conversion");
         let encoded = urlencoding::encode(&json);
@@ -382,6 +418,7 @@ impl State {
     }
 }
 
+/// Types of coumpounds: for pse I am only using PDB
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "lowercase")]
 pub enum ParseFormatT {
@@ -396,6 +433,7 @@ pub struct ParseParams {
     pub format: ParseFormatT,
 }
 
+/// StructureType. Useful for specifying more complicated sets of structures
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "snake_case")]
 pub enum StructureTypeT {
@@ -410,6 +448,7 @@ impl Default for StructureTypeT {
     }
 }
 
+/// Structure Params
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 pub struct StructureParams {
     #[serde(rename = "type")]
@@ -432,6 +471,10 @@ pub struct StructureParams {
     pub ijk_max: Option<(i32, i32, i32)>,
 }
 
+/// Component Selector Type
+///
+/// Useful for specifying broad groups like 'all',
+/// 'protein', etc.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "snake_case")]
 pub enum ComponentSelectorT {
@@ -444,7 +487,7 @@ pub enum ComponentSelectorT {
     Ion,
     Water,
 }
-
+/// Component Expresssion
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 pub struct ComponentExpression {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -481,6 +524,7 @@ pub struct ComponentExpression {
     pub atom_index: Option<i32>,
 }
 
+/// Representation Type
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "snake_case")]
 pub enum RepresentationTypeT {
@@ -489,6 +533,7 @@ pub enum RepresentationTypeT {
     Surface,
 }
 
+/// Color Names
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "lowercase")]
 pub enum ColorNamesT {
@@ -641,6 +686,7 @@ pub enum ColorNamesT {
     Yellowgreen,
 }
 
+/// Color Type: Named or Hex
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(untagged)]
 pub enum ColorT {

src/pymolparsing/parsing.rs

@@ -15,7 +15,8 @@
 //!
 //! ## Links
 //!
-//! - [Molecule Experter](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L1627)
+//! - [pymol-open-source](https://github.com/schrodinger/pymol-open-source). Pymol Source code.
+//! - [Molecule Exporter](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L1627)
 //! - [PymolMoleculeExporter](https://github.com/schrodinger/pymol-open-source/blob/03d7a7fcf0bd95cd93d710a1268dbace2ed77765/layer4/Cmd.cpp#L3877)
 //! - [PDB Exporter](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L1627)
 //! - [MoleculeExporterPDB](https://github.com/schrodinger/pymol-open-source/blob/master/layer3/MoleculeExporter.cpp#L439)
@@ -477,6 +478,10 @@ impl PyObjectMolecule {
     }
 }
 
+/// PymolSessionObjectData
+///
+/// Differentiate between serializing an object or a selection
+/// They have different `shapes` and require custom deserialization.
 #[derive(Debug, Serialize)]
 #[serde(untagged)]
 pub enum PymolSessionObjectData {
@@ -623,7 +628,11 @@ impl<'de> Deserialize<'de> for SceneView {
         }
     }
 }
-
+/// SessionName
+///
+/// High level info about a session obeject.
+/// Can be an object/molecule or a selection
+///
 #[derive(Debug, Deserialize, Serialize)]
 pub struct SessionName {
     pub name: String,
@@ -635,6 +644,10 @@ pub struct SessionName {
     pub group: String,
 }
 
+/// Session Selector
+///
+/// Defines a pymole seleciton in terms of names and
+/// atom indices.
 #[derive(Debug, Serialize)]
 pub struct SessionSelector {
     // SelectorAsPyList
@@ -686,6 +699,11 @@ impl SessionSelectorList {
     }
 }
 
+/// Global Pymol Settings
+///
+/// This enum is derived from [SettingInfo.h](https://github.com/schrodinger/pymol-open-source/blob/master/layer1/SettingInfo.h),
+/// pymol's setting specification
+///
 #[derive(Serialize_repr, Deserialize_repr, PartialEq, Debug, Clone)]
 #[repr(u32)]
 pub enum SettingsEnum {

src/pymolparsing/psedata.rs

@@ -5,28 +5,6 @@
 //! Currently the parsers are working for small test cases of molecules and selections. Additional parser structs would be required for
 //! other PSE data types which include the folloing:
 //!
-//! ## PyObject Serialization
-//!
-//! Code:
-//! -[pyobject](https://github.com/schrodinger/pymol-open-source/blob/03d7a7fcf0bd95cd93d710a1268dbace2ed77765/layer1/PyMOLObject.cpp#L681)
-//!
-//! Python Obects:
-//! - Object
-//! - Gadget
-//! - Molecule    ---> WIP.
-//! - Dist
-//! - Map
-//! - Mesh
-//! - Slice
-//! - Surface
-//! - CGO
-//! - Alignment
-//! - Group
-//! - Volume
-//! - Callback
-//! - Curve
-//! - Selection ---> WIP.
-//!
 
 use crate::molviewspec::nodes::{self as mvsnodes, CameraParams, ColorNamesT, State};
 use crate::pymolparsing::parsing::{
@@ -44,7 +22,11 @@ use std::path::Path;
 
 /// PSEData represents the structure of a PyMOL Session File (PSE).
 ///
-/// This struct contains various components of a PyMOL session, including:
+/// We lean heavily on `serde_pickle` to deserialize the PSE binary
+/// file into named structs, of which `PSEData` is the highlest level object containing
+/// most of the required methods for operating on PSE files.
+///
+///  This struct contains various components of a PyMOL session, including:
 /// - Version information
 /// - Color settings
 /// - View settings
@@ -53,8 +35,28 @@ use std::path::Path;
 /// - Cached data
 /// - Session names and associated objects
 ///
-/// It provides methods for loading PSE files, converting to JSON,
-/// extracting molecule and selection data, and creating PDB files.
+/// To be implemented in time:
+///
+/// PyObject :
+/// -[pyobject](https://github.com/schrodinger/pymol-open-source/blob/03d7a7fcf0bd95cd93d710a1268dbace2ed77765/layer1/PyMOLObject.cpp#L681)
+///
+/// Python Obects:
+/// - Object
+/// - Gadget
+/// - Molecule    ---> WIP.
+/// - Dist
+/// - Map
+/// - Mesh
+/// - Slice
+/// - Surface
+/// - CGO
+/// - Alignment
+/// - Group
+/// - Volume
+/// - Callback
+/// - Curve
+/// - Selection ---> WIP.
+///
 #[derive(Debug, Deserialize, Serialize)]
 pub struct PSEData {
     pub version: i32,
@@ -72,7 +74,7 @@ pub struct PSEData {
     moviescenes: Vec<Vec<i32>>,
     // High level state settings: we need to prpogate these..
     pub settings: Vec<Settings>,
-    movie: (
+    pub movie: (
         i32,
         i32,
         Vec<f32>,