Merge pull request #1 from molstar/pub-updates

Add docs on animations, primitives, and volumes

Author: sbittrich

docs/animations.md

@@ -0,0 +1,39 @@
+# MolViewSpec animations
+
+Animations are sequential collections of individual MolViewSpec scenes. You can combine them freely into complex stories
+that render scenes one-by-one. The Mol* viewer can interpolate between these states, providing you with a powerful story
+telling tool tailored to structural biology.
+
+## Creating snapshots
+
+Use the builder as normal and define the desired scene. Invoke `get_snapshot()` to obtain a snapshot instance (in 
+contrast to the default way of emitting the generated state description using `get_state()`).
+
+```python
+snapshot1 = builder.get_snapshot(
+    title="1tqn",
+    description="""
+### 1tqn with ligand and electron density map
+- 2FO-FC at 1.5σ, blue
+- FO-FC (positive) at 3σ, green
+- FO-FC (negative) at -3σ, red
+""",
+)
+```
+
+A snapshot can hold additional metadata such as a custom title and description. Markup is supported.
+
+## Combining snapshots
+
+Individual snapshots can then be combined into an animation by providing them in the desired order using the `snapshots`
+parameter. Additionally, global metadata can be added that describes shared properties of all snapshots.
+
+```python
+states = States(snapshots=[snapshot1, snapshot2], metadata=GlobalMetadata(description="1tqn + Volume Server")).json(
+    exclude_none=True, indent=2
+)
+```
+
+The output is valid MolViewSpec JSON that can be opened in Mol*. Mol* will interpolate between individual substates and 
+add smooth transitions by default. You can further customize this behavior using the `transition_duration_ms` and 
+`linger_duration_ms` properties. 

docs/demos.md

@@ -0,0 +1,18 @@
+# Demonstrations
+
+The following demos showcase how MolViewSpec helps with creating interactive stories and visualizations.
+
+## [Kinases Story](https://molstar.org/demos/mvs-kinase-story/)
+
+BCR-ABL is a classic case of how structural biology can drive drug discovery. This story will help you 
+understand the role of BCR-ABL in chronic myeloid leukemia and how the drug Imatinib works. The source code can be found
+[here](https://github.com/molstar/molstar/tree/master/src/examples).
+
+[![Kinases Story](./files/kinases.png 'Kinases Story')](https://molstar.org/demos/mvs-kinase-story/)
+
+## [I/HM Restraints](https://molstar.org/demos/ihm-restraints/)
+
+Visualize structural restraints for integrated hybrid models (I/HM). The source code can be found 
+[here](https://github.com/molstar/molstar/tree/master/src/examples).
+
+[![I/HM Restraints](./files/ihm-restraints.png 'I/HM Restraints')](https://molstar.org/demos/ihm-restraints/)