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)
  • Terminology (MolSysMT-aligned)
  • Page anchors (labels)
  • File types
  • Page roles (what goes where)
  • HTML lite (preferred for 3D visuals)
  • Notebook execution and widget state
  • Notebook source formatting (keep diffs clean)
  • Avoid accidental style drift
  • Section index pages (toctrees)
  • Page naming and discoverability
  • User-facing API naming (avoid unit suffixes)
  • Experimental features
  • Cross-links and references
  • External links (avoid repetition)
  • API-link density (readability first)
  • Code conventions in user-facing docs
• 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
  • Page links: {doc} for intra-section navigation
  • File-based links (when they are acceptable)
  • External links (first-mention rule)
  • Cross-linking between major sections
  • Migration notes and legacy links
  • When you move pages: keep labels honest