Documentation Topics

[arose]

Please, feel free to suggest other topics or pick one to work on. This is for the library docs created in https://github.com/molstar/docs (available at https://molstar.org/docs/).

• [ ] How to contribute to the documentation
• [ ] Interrogate the underlying model data (atoms, residues, distances etc), see #20
• [ ] Approaches for converting a NGL or LiteMol app, see #20
• [ ] Working with custom shapes (creating, zooming), see #134

[JuroOravec]

Hi, in my case, I was looking at Molstar as a potential visualisation lib (e.g. similar to the Alpha Orbitals example).

Molstar is great in regards to features and modularity. The Plugin design seems like it could provide an easy way to intercept / listen to user and system events.

However, just understanding what's possible with the Plugins, and their Behaviors and Actions, requires a lot of upfront work. So I suggest adding "Expanding on the Creating Plugin Instance guide" to the list.

Some things that are not clear from that guide as-it-is:

• What even is a plugin?
  • What does it represent?
  • What parts of the Molstar app does it touch / affect? Can I use it to listen and intercept to events? Can I use it to modify some existing functionality?
• Go over each prop on PluginSpec and explain what it does.
  • It's not clear how the Actions and Behaviors work, without going into the code. Are they triggered in sequence, or on some triggers? If triggers, then what are the triggers? Do Actions and Behaviors have to return a value, or is it optional? Can I modify the conditions when they are triggered, or would this have to be handled inside the Action or Behavior?
  • While all default Actions and Behaviors can be seen in DefaultPluginSpec, and their names are transparent, you still need familiarity to know where you would use them. A little description on each of them would help.
• Following should maybe be in a separate page, but there's missing info on what config options, behaviours and actions are supported. They can be found in the source code, but the issue is that if these are not covered in a public documentation / wiki, I can't determine which ones are supported, and which are internal / up-for-change. And in such case, I'm not confident in introducing Molstar to another project.
  • E.g. in case of the above-mentioned guide, it would really help if the Viewer options were documented explicitly, instead of linking to the source file. Same for the default Behaviors and Actions.

I'm sorry I can't contribute to the document write up directly, I'm already spread too thin. I hope, though, that the above can be used as a starting points for when the documentation would be expanded.

[ywu]

Is there any guidelines for how to write a new parser for file format that is not supported? Edit: In one specific case, we already have a python module to do the parsing, and I am wondering if it's possible to run that to parse and then pass and adjust the structure/MD-trajectory data to molstar.

[dsehnal]

@ywu I've added https://molstar.org/docs/transforms/custom-trajectory.html to the docs. Hopefully, it will help you. If you need more help with the topic, please create a separate issue to discuss it.

[ywu]

Thanks so much, David. That's exactly what I'm looking for to get started.

On Mon, Jun 28, 2021 at 8:39 AM David Sehnal @.***> wrote:

@ywu https://github.com/ywu I've added https://molstar.org/docs/transforms/custom-trajectory.html to the docs. Hopefully, it will help you. If you need more help with the topic, please create a separate issue to discuss it.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/molstar/molstar/issues/138#issuecomment-869649636, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAB7UFV7HWDRN73WL4DOSD3TVBURRANCNFSM4ZEVCMUQ .

[klaemo]

Adding to what @JuroOravec already mentioned, I'd really appreciate documentation describing how to use mol* as a library.

Here's some context: I'm an experienced web developer with little to no knowledge about chemistry. I'm currently working on embedding mol* without its UI into our product. So, for me it would be helpful to have some explainers of the underlying concepts of the mol* API or even an API documentation at all. Currently I'm exploring the TypeScript types (which are great!) in a trial & error kind of way. As the API is rather complex and not very self-describing this is rather tedious.

When I first found https://molstar.org/docs I was confused that it was referring to "plugins" before introducing how to get a simple viewer instance running...until I found out plugins aren't actually plugins but the viewer itself.

Further I'd like to understand

• builders and managers and how they relate to each other
• how to add (figured that out already) and remove representations
• animations
• selections
• commands
• behaviors
• state

Basically, how do I interact with mol* as a developer?

I don't mean this to sound demanding as I know this is an open source project. Just wanted to give a POV what developers might be interested in.

[dsehnal]

Thanks for the feedback @klaemo. The learning curve for this is definitely quite high and the lack of docs isn't helping.

To help us get started on it, do you think you would be able to find some time to add the topics directly to the documentation repository (as pull request(s)) where you fill in some of the things you've figured out and leave other as TODO placeholders?

[hainm]

The learning curve for this is definitely quite high

yeah, especially for people like me that is not really good at JS code.

• [ ] I have a question about design: What's the relationship among those: model, structure, trajectory, component?-

[dhrblav]

Recently I came across VTK.js and its documentation. They provide some nice and simple slideshow tutorials that help a lot easing the learning curve, e.g. the Architecture and Tooling tutorial. May I kindly but strongly suggest Mol* principal architects to provide this kind of architecture document at a conceptual level, using only few words and pictures in a simple slideshow? I suppose the writing task should be lightweight, can be done incrementally, and will make Mol* API much more accessible to mere mortals.

[cmdcolin]

would be curious about docs for using the library from a 'developer' point of view e.g. installing from NPM, getting a basic PDB to display on a create-react-app/vite instance.

I would additionally like to have things like mouseovers /annotation callouts on parts of the structure. i managed to do this with NGL in my app (https://github.com/GMOD/react-msaview/blob/27bc3d53cfb41770d06f9e9d94e74369217e2470/app/src/ProteinPanel.tsx for reference to any interested readers) but I'm interested in molstar as an 'evolution' to this...

[chdominguez]

Is the documentation still being developed?

I think Mol* really needs proper documentation and examples. It's a very powerful and versatile molecular visualizer, but for the users, without knowing how it works, it just feels complicated.

[0xorial]

Even a brief couple of paragraphs write could be of great help to people trying to use it!