Merge pull request #63 from openforcefield/move_faq

Move FAQ from Toolkit

Author: Yoshanuikabundi

devtools/conda-envs/rtd_env.yml

@@ -1,24 +1,24 @@
 name: openff-toolkit-docs
 channels:
-    - conda-forge
+  - conda-forge
 dependencies:
-    - pip
-    # readthedocs dependencies
-    - sphinx>=5,<7
-    - myst-parser>=1,<2
-    # - myst-nb
-    - sphinx-notfound-page
-    - ipython >=8.8
-    - sphinx-design
-    # Examples
-    - gitpython
-    - nbconvert
-    - nbformat
-    # Theme
-    - pip:
-        # Theme
-        - git+https://github.com/openforcefield/openff-sphinx-theme.git@main
-        # Lints
-        - sphinxawesome-codelinter
-        # Sphinx
-        - git+https://github.com/Yoshanuikabundi/MyST-NB.git@upgrade-to-1
+  - pip
+  # readthedocs dependencies
+  - sphinx>=5,<7
+  - myst-parser>=1,<2
+  # - myst-nb
+  - sphinx-notfound-page
+  - ipython >=8.8
+  - sphinx-design>=0.6.0
+  # Examples
+  - gitpython
+  - nbconvert
+  - nbformat
+  # Theme
+  - pip:
+      # Theme
+      - git+https://github.com/openforcefield/openff-sphinx-theme.git@main
+      # Lints
+      - sphinxawesome-codelinter
+      # Sphinx
+      - git+https://github.com/Yoshanuikabundi/MyST-NB.git@upgrade-to-1

source/_ext/check_python_codeblocks.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Conditionally provide some variables to a wrapped script.
+
+The purpose of this script is to provide the ability to quickly write short
+snippets in the OpenFF documentation that do not require initialization of
+common Toolkit objects while not inhibiting the quality of error messages from
+more complete code examples.
+
+Code examples are used throughout the docs and testing that they do not raise
+errors has caught many documentation errors already. The `codelinter` Sphinx
+extension runs this script on all code blocks in this documentation project.
+The script sets up some commonly used variables and imports so that short
+snippets don't have to initialize them, and then sets up an import hook that
+deletes the added names if `openff.toolkit` is imported in the code block. This
+means that short snippets can assume some common variables are in scope, but
+long code blocks intended to be self-sufficient can opt out of this name
+pollution by importing the toolkit.
+"""
+
+# Define the default namespace
+import openff.toolkit
+from openff.toolkit import ForceField, Molecule, Topology
+
+molecule = Molecule.from_smiles("C123C(C1)(C2)C3")
+topology = Topology.from_molecules([molecule])
+force_field = ForceField("openff_unconstrained-2.2.0.offxml")
+ff_unconstrained = force_field
+ff_constrained = ForceField("openff-2.2.0.offxml")
+
+# Set the import hook
+import builtins
+import sys
+
+_old_import = __import__
+_already_deleted = False
+
+
+def __import__(name, *args, **kwargs):
+    """
+    Clear above variables on any new import of the toolkit
+    """
+    global _already_deleted
+    if name.startswith("openff.toolkit") and not _already_deleted:
+        global \
+            molecule, \
+            topology, \
+            force_field, \
+            ForceField, \
+            Molecule, \
+            Topology, \
+            ff_constrained, \
+            ff_unconstrained
+        del (
+            molecule,
+            topology,
+            force_field,
+            ForceField,
+            Molecule,
+            Topology,
+            ff_constrained,
+            ff_unconstrained,
+        )
+        _already_deleted = True
+
+    return _old_import(name, *args, **kwargs)
+
+
+builtins.__import__ = __import__
+
+# Execute the code block
+exec(sys.stdin.read())

source/_static/css/faq.css

@@ -0,0 +1,10 @@
+details.faq.sd-dropdown,
+details.faq.sd-dropdown summary,
+details.faq.sd-dropdown:not([open]) > .sd-card-header {
+    border: None;
+}
+
+details.faq.sd-dropdown summary.sd-summary-title .sd-summary-state-marker {
+    min-width: 3em;
+    transform-origin: 25% 50%;
+}

source/conf.py

@@ -79,6 +79,18 @@
     "openff.recharge": ("https://docs.openforcefield.org/recharge/en/stable", None),
     "openff.nagl": ("https://docs.openforcefield.org/nagl/en/stable", None),
 }
+intersphinx_disabled_reftypes = ["*"]
+myst_heading_anchors = 2
+
+sd_custom_directives = {
+    "faq-entry": {
+        "inherit": "dropdown",
+        "options": {
+            "animate": "fade-in-slide-down",
+            "class-container": "faq",
+        },
+    }
+}
 
 # sphinx-notfound-page
 # https://github.com/readthedocs/sphinx-notfound-page
@@ -104,7 +116,7 @@
 extensions.append("sphinxawesome.codelinter")
 codelinter_languages = {
     # Language: command to pass codeblock as stdin
-    "python": "python",
+    "python": "python source/_ext/check_python_codeblocks.py",
 }
 # Tell MyST-NB about codelinter builder
 nb_mime_priority_overrides = [
@@ -113,6 +125,9 @@
 
 # Configure the linkcheck builder
 linkcheck_anchors = False  # This generates lots of false positives
+linkcheck_ignore = [
+    r'https://pubs.acs.org/doi/' # ACS 403s the link checker. Thanks ACS.
+]
 
 # Cookbook stuff
 import sys
@@ -132,6 +147,7 @@
 html_css_files = [
     "css/deflist-flowchart.css",
     "css/cookbook.css",
+    "css/faq.css",
 ]
 
 # List of patterns, relative to source directory, that match files and