Documentation for the web

This section collects guidelines and examples for writing MolSysViewer’s web documentation with MyST and Sphinx. It is aimed at contributors who edit the User Guide, Showcase, Cookbook, and developer documentation.

• Use myst.ipynb to see concrete examples of MyST admonitions and how to structure tutorial notebooks.

• Use editorial_guidelines.md as the source of truth for file types, section roles, and the HTML lite workflow.

• Use build_and_layout.md when you need to change the docs build or layout conventions.

• If you execute docs notebooks to freeze outputs, use docs/execute_notebooks.py. It strips ipywidgets/AnyWidget state by default. Tag a cell with keep-widget-state only if you need to preserve a widget-based output.

• Use references.md as the reference for cross-links between pages and API objects (labels, {ref}, {func}, {class}, etc.).

• Web documentation editorial guidelines
  • Why this exists
  • Writing style (always)
  • File types
  • Page roles (what goes where)
  • HTML lite (preferred for 3D visuals)
  • Notebook execution and widget state
  • Avoid accidental style drift
  • Cross-links and references
• Web docs build & layout
  • Objectives
  • Build & tooling
  • Directory layout
  • Assets and hygiene
• MyST in MolSysViewer documentation
  • Recommended admonitions in MolSysViewer
  • Default MyST admonitions
• References and Cross-links in Documentation
  • Section labels and {ref} roles
  • Page-level labels for tutorials and recipes
  • API references: {func}, {class}, and friends
  • File-based links (when they are acceptable)
  • Cross-linking between major sections
  • Migration notes and legacy links