Add sphinx.ext.intersphinx (#22)

Author: ianmkenney

docs/conf.py

@@ -13,12 +13,14 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
+intersphinx_mapping = {
+    "gufe": ("https://gufe.openfree.energy/en/stable", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/getting_started.rst

@@ -21,7 +21,7 @@ Verify the installation was successful in a Python interpreter
 3. Quick-start example
 ~~~~~~~~~~~~~~~~~~~~~~
 
-You can calculate transformation weights for an ``AlchemicalNetwork``, ``alchem_network`` by calling a strategy's ``propose`` method.
+You can calculate transformation weights for an :external+gufe:py:class:`~gufe.network.AlchemicalNetwork`, ``alchem_network`` by calling a strategy's ``propose`` method.
 
 
 .. code:: python
@@ -36,10 +36,10 @@ You can calculate transformation weights for an ``AlchemicalNetwork``, ``alchem_
    strategy_result: StrategyResult = strategy.propose(alchem_network, previous_results)
 
 
-This returns a ``StrategyResult`` object, which is a mapping between the transformations in an ``AlchemicalNetwork`` and the weights determined by the strategy.
-``None`` weights are a terminating case: a transformation with a ``None`` weight won't be proposed again and a ``StrategyResult`` with only ``None`` weights is "complete".
+This returns a :py:class:`~stratocaster.base.strategy.StrategyResult` object, which is a mapping between the transformations in an :external+gufe:py:class:`~gufe.network.AlchemicalNetwork` and the weights determined by the strategy.
+``None`` weights are a terminating case: a transformation with a ``None`` weight won't be proposed again and a :py:class:`~stratocaster.base.strategy.StrategyResult` with only ``None`` weights is "complete".
 
-Calls to ``propose`` are deterministic and guaranteed to reach a terminating condition if the resulting weights are used to update the ``ProtocolResult`` objects in ``previous_results``.
+Calls to ``propose`` are deterministic and guaranteed to reach a terminating condition if the resulting weights are used to update the :external+gufe:py:class:`~gufe.protocols.protocol.ProtocolResult` objects in ``previous_results``.
 See the :ref:`user guide<user-guide-label>` for an example of this process.
 
 Other resources

docs/user_guide.rst

@@ -3,11 +3,12 @@
 User Guide
 ==========
 
-A ``Strategy`` is an algorithm that assists in traversing the execution path of transformations within ``gufe`` ``AlchemicalNetwork`` objects.
+A :py:class:`~stratocaster.base.strategy.Strategy` is an algorithm that assists in traversing the execution path of transformations within ``gufe`` :external+gufe:py:class:`~gufe.network.AlchemicalNetwork` objects.
 It removes the burden for an individual or execution engine to determine which transformations in a network must be performed and how important one transformation is relative to another given results that have already been collected.
 For instance, transformations with many previously calculated repeats might have a lower priority compared to transformations that haven't been performed at all.
-This prioritization is encoded by transformation weights, which are presented for an ``AlchemicalNetwork`` given a set of previously computed results.
+This prioritization is encoded by transformation weights, which are presented for an :external+gufe:py:class:`~gufe.network.AlchemicalNetwork` given a set of previously computed results.
 As results are accumulated, the strategy must eventually reach a terminating condition where no weights are presented.
+
 Valid strategies are deterministic, i.e. networks with a fixed set of previous results always return the same weights.
 While the details of selecting and running a transformation from the weights is out of scope for ``stratocaster``, the following code demonstrates where a strategy might fit in an iterative execution workflow.
 
@@ -16,27 +17,27 @@ While the details of selecting and running a transformation from the weights is
 A ``None`` weight for a transformation means the transformation should not be performed again as more results are added.
 This differs from a zero weight, which could mean the transformation will eventually be proposed again with more results.
 Note that before ``resolve`` (which returns a normalized set of weights) is called, the magnitudes of the weights are arbitrary and may reflect the underlying logic behind the specific strategy implementation.
-For example, the ``ConnectivityStrategy`` weights are, before correcting for repeated calculations, the average number of connections of the transformations' end states.
-Therefore, the pre-normalization weights directly report properties of the many subgraphs in the ``AlchemicalNetwork``.
+For example, the :py:class:`~stratocaster.strategies.ConnectivityStrategy` weights are, before correcting for repeated calculations, the average number of connections of the transformations' end states.
+Therefore, the pre-normalization weights directly report properties of the many subgraphs in the :py:class:`~gufe.network.AlchemicalNetwork`.
 
 Defining a new ``Strategy``
 ---------------------------
 
-A new ``Strategy`` implementation requires definitions of a new ``Strategy`` subclass along with a ``StrategySettings`` subclass specific to the new strategy.
+A new :py:class:`~stratocaster.base.strategy.Strategy` implementation requires definitions of a new :py:class:`~stratocaster.base.strategy.Strategy` subclass along with a :py:class:`~stratocaster.base.models.StrategySettings` subclass specific to the new strategy.
 
-The new ``StrategySettings`` is the mechanism by which a user will alter behavior of the new ``Strategy``.
-As such, it should define the relevant variables on which the ``Strategy`` will depend.
+The new ``StrategySettings`` is the mechanism by which a user will alter behavior of the new :py:class:`~stratocaster.base.strategy.Strategy`.
+As such, it should define the relevant variables on which the :py:class:`~stratocaster.base.strategy.Strategy` will depend.
 In the below example, we include only a ``max_runs`` setting, which is usually enough to guarantee that the strategy reaches a termination condition.
 
-The new ``Strategy`` implementation involves three main steps: 1) linking the strategy to its settings class, 2) defining the ``_default_settings`` class method, and 3) defining the ``_propose`` method.
+The new :py:class:`~stratocaster.base.strategy.Strategy` implementation involves three main steps: 1) linking the strategy to its settings class, 2) defining the ``_default_settings`` class method, and 3) defining the ``_propose`` method.
 
 .. literalinclude:: ./code/newstrat.py
 
 A definition of ``_settings_cls`` provides a guardrail by preventing a user of your strategy from supplying an unexpected settings type.
 Defining ``_default_settings`` allows a user to get the default settings through ``MyCustomStrategy.default_settings()``.
 If your settings provide an exhaustive set of default options, simply return an instance of your settings without providing hard-coded keyword arguments.
 
-Lastly, the ``_propose`` method implementation determines the results of a strategy prediction based on the ``AlchemicalNetwork``, prior results from executing ``Transformation`` protocols, and your settings.
-This method should be deterministic: repeated proposals given the same set of results will yield the same ``StrategyResult``.
+Lastly, the ``_propose`` method implementation determines the results of a strategy prediction based on the :external+gufe:py:class:`~gufe.network.AlchemicalNetwork`, prior results from executing :external+gufe:py:class:`~gufe.transformations.transformation.Transformation` protocols, and your settings.
+This method should be deterministic: repeated proposals given the same set of results will yield the same :py:class:`~stratocaster.base.StrategyResult`.
 It should also have a clear termination condition.
-If results are accumulated as a result of the recommendations provided by the strategy, the ``StrategyResult`` will eventually return ``None`` weights for all transformations in the network.
+If results are accumulated as a result of the recommendations provided by the strategy, the :py:class:`~stratocaster.base.StrategyResult` will eventually return ``None`` weights for all transformations in the network.