From 50be21dbfe434b88d1ae51e8cdedf010f5ddfb6b Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 6 Nov 2026 13:15:31 +0100 Subject: [PATCH 1/2] Rename cookbook to how-to-guides --- docs/guide/execution/index.rst | 14 ++++++------ docs/guide/execution/quickrun_execution.rst | 18 +++++++-------- docs/guide/protocols/absolutebinding.rst | 4 ++-- docs/guide/protocols/absolutesolvation.rst | 4 ++-- docs/guide/protocols/index.rst | 2 +- .../protocols/relativehybridtopology.rst | 4 ++-- docs/guide/protocols/septop.rst | 4 ++-- docs/guide/results/index.rst | 4 ++-- docs/guide/results/simulation_health.rst | 2 +- docs/guide/setup/index.rst | 22 +++++++++---------- .../bespoke_parameters.nblink | 0 .../choose_protocol.nblink | 0 .../create_alchemical_network.nblink | 0 .../dumping_transformation.rst | 0 .../generate_ligand_network.nblink | 0 .../hand_write_ligand_network.nblink | 0 docs/{cookbook => how_to_guides}/index.rst | 0 .../jq_inspection.rst | 0 .../ligandnetwork_vis.nblink | 0 .../loading_molecules.nblink | 0 .../network_from_orion_fepp.nblink | 0 .../packmol_memgen_setup.nblink | 0 .../repairing_broken_networks.nblink | 0 .../resume_quickrun.rst | 0 .../rfe_alchemical_planners.nblink | 0 .../run_on_slurm.rst | 0 .../run_quickrun.rst | 0 .../run_repeats_in_parallel.rst | 0 .../run_task_based.rst | 0 .../run_with_mps.rst | 0 .../user_charges.nblink | 0 docs/index.rst | 2 +- 32 files changed, 40 insertions(+), 40 deletions(-) rename docs/{cookbook => how_to_guides}/bespoke_parameters.nblink (100%) rename docs/{cookbook => how_to_guides}/choose_protocol.nblink (100%) rename docs/{cookbook => how_to_guides}/create_alchemical_network.nblink (100%) rename docs/{cookbook => how_to_guides}/dumping_transformation.rst (100%) rename docs/{cookbook => how_to_guides}/generate_ligand_network.nblink (100%) rename docs/{cookbook => how_to_guides}/hand_write_ligand_network.nblink (100%) rename docs/{cookbook => how_to_guides}/index.rst (100%) rename docs/{cookbook => how_to_guides}/jq_inspection.rst (100%) rename docs/{cookbook => how_to_guides}/ligandnetwork_vis.nblink (100%) rename docs/{cookbook => how_to_guides}/loading_molecules.nblink (100%) rename docs/{cookbook => how_to_guides}/network_from_orion_fepp.nblink (100%) rename docs/{cookbook => how_to_guides}/packmol_memgen_setup.nblink (100%) rename docs/{cookbook => how_to_guides}/repairing_broken_networks.nblink (100%) rename docs/{cookbook => how_to_guides}/resume_quickrun.rst (100%) rename docs/{cookbook => how_to_guides}/rfe_alchemical_planners.nblink (100%) rename docs/{cookbook => how_to_guides}/run_on_slurm.rst (100%) rename docs/{cookbook => how_to_guides}/run_quickrun.rst (100%) rename docs/{cookbook => how_to_guides}/run_repeats_in_parallel.rst (100%) rename docs/{cookbook => how_to_guides}/run_task_based.rst (100%) rename docs/{cookbook => how_to_guides}/run_with_mps.rst (100%) rename docs/{cookbook => how_to_guides}/user_charges.nblink (100%) diff --git a/docs/guide/execution/index.rst b/docs/guide/execution/index.rst index dff9b6578..8b1a5b05d 100644 --- a/docs/guide/execution/index.rst +++ b/docs/guide/execution/index.rst @@ -25,10 +25,10 @@ Both can be used from the command line or from Python. .. admonition:: Related How-To Guides - * :doc:`/cookbook/dumping_transformation` - * :doc:`/cookbook/run_quickrun` - * :doc:`/cookbook/resume_quickrun` - * :doc:`/cookbook/run_on_slurm` - * :doc:`/cookbook/run_repeats_in_parallel` - * :doc:`/cookbook/run_with_mps` - * :doc:`/cookbook/run_task_based` + * :doc:`/how_to_guides/dumping_transformation` + * :doc:`/how_to_guides/run_quickrun` + * :doc:`/how_to_guides/resume_quickrun` + * :doc:`/how_to_guides/run_on_slurm` + * :doc:`/how_to_guides/run_repeats_in_parallel` + * :doc:`/how_to_guides/run_with_mps` + * :doc:`/how_to_guides/run_task_based` diff --git a/docs/guide/execution/quickrun_execution.rst b/docs/guide/execution/quickrun_execution.rst index 8808722e2..e962a1485 100644 --- a/docs/guide/execution/quickrun_execution.rst +++ b/docs/guide/execution/quickrun_execution.rst @@ -28,16 +28,16 @@ and writes the free energy estimate and its uncertainty to the results file. quickrun keeps track of which tasks have finished, so an interrupted run can be resumed with ``--resume``. Finished tasks are skipped, and an interrupted simulation continues from its last checkpoint -(see :doc:`/cookbook/resume_quickrun`). +(see :doc:`/how_to_guides/resume_quickrun`). Organizing a campaign --------------------- You decide where and when each Transformation runs, for example by -:doc:`submitting one job per Transformation to a cluster `. +:doc:`submitting one job per Transformation to a cluster `. You can run multiple simulations in parallel by running several quickrun calls at the same time, -for example one per Transformation, :doc:`one per repeat `, -or :doc:`several on the same GPU `. +for example one per Transformation, :doc:`one per repeat `, +or :doc:`several on the same GPU `. The results files are then collected with :ref:`openfe gather `. .. TODO: link the "Gather free energy results" how-to instead of the CLI reference once it exists. @@ -47,11 +47,11 @@ see :ref:`userguide_task_based_execution`. .. admonition:: How-to guides - * :doc:`/cookbook/run_quickrun` - * :doc:`/cookbook/resume_quickrun` - * :doc:`/cookbook/run_on_slurm` - * :doc:`/cookbook/run_repeats_in_parallel` - * :doc:`/cookbook/run_with_mps` + * :doc:`/how_to_guides/run_quickrun` + * :doc:`/how_to_guides/resume_quickrun` + * :doc:`/how_to_guides/run_on_slurm` + * :doc:`/how_to_guides/run_repeats_in_parallel` + * :doc:`/how_to_guides/run_with_mps` See Also -------- diff --git a/docs/guide/protocols/absolutebinding.rst b/docs/guide/protocols/absolutebinding.rst index bd43f6cac..c9986f433 100644 --- a/docs/guide/protocols/absolutebinding.rst +++ b/docs/guide/protocols/absolutebinding.rst @@ -132,7 +132,7 @@ the `Boresch restraint analysis tutorial The multistate trajectory (``simulation.nc``) and its topology (``alchemical_system.pdb``) can be analysed further using `openfe_analysis`_. -.. TODO: Link to the trajectory visualisation cookbook when published. +.. TODO: Link to the trajectory visualisation how_to_guide when published. See Also -------- @@ -154,7 +154,7 @@ See Also **How-to guides** -:ref:`How-to guides ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/protocols/absolutesolvation.rst b/docs/guide/protocols/absolutesolvation.rst index db491e914..bdd10fc5e 100644 --- a/docs/guide/protocols/absolutesolvation.rst +++ b/docs/guide/protocols/absolutesolvation.rst @@ -115,7 +115,7 @@ the structural analysis is skipped. The multistate trajectories (``solvent.nc`` and ``vacuum.nc``) can be analysed further using `openfe_analysis`_. -.. TODO: Link to the trajectory visualisation cookbook when published. +.. TODO: Link to the trajectory visualisation how_to_guide when published. See Also @@ -135,7 +135,7 @@ See Also **How-to guides** -:ref:`How-to guides ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/protocols/index.rst b/docs/guide/protocols/index.rst index 9d32d711a..f67ccf3c1 100644 --- a/docs/guide/protocols/index.rst +++ b/docs/guide/protocols/index.rst @@ -243,7 +243,7 @@ These limitations apply to all binding free energy protocols. See also -------- -* :doc:`Choose and configure a protocol ` +* :doc:`Choose and configure a protocol ` * :ref:`Assessing simulation health ` * :doc:`Troubleshooting simulations ` diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst index b35d513cf..b8dee3515 100644 --- a/docs/guide/protocols/relativehybridtopology.rst +++ b/docs/guide/protocols/relativehybridtopology.rst @@ -201,7 +201,7 @@ evidence of ligand displacement. The multistate trajectory (``simulation.nc``) and the hybrid topology (``hybrid_system.pdb``) can be analysed further using `openfe_analysis`_. -.. TODO: Link to the trajectory visualisation cookbook when published. +.. TODO: Link to the trajectory visualisation how_to_guide when published. See Also @@ -219,7 +219,7 @@ See Also **How-to guides** -:ref:`How-to guides ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst index 30b7fe706..de10a567b 100644 --- a/docs/guide/protocols/septop.rst +++ b/docs/guide/protocols/septop.rst @@ -144,7 +144,7 @@ the `Boresch restraint analysis tutorial The multistate trajectory (``simulation.nc``) and its topology (``alchemical_system.pdb``) can be analysed further using `openfe_analysis`_. -.. TODO: Link to the trajectory visualisation cookbook when published. +.. TODO: Link to the trajectory visualisation how_to_guide when published. See Also -------- @@ -165,7 +165,7 @@ See Also **How-to guides** -:ref:`How-to guides ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/results/index.rst b/docs/guide/results/index.rst index 958ec7753..575822d8a 100644 --- a/docs/guide/results/index.rst +++ b/docs/guide/results/index.rst @@ -14,7 +14,7 @@ and entire networks of results analysed. .. admonition:: How-to guides - * :doc:`/cookbook/dumping_transformation` - * :doc:`/cookbook/jq_inspection` + * :doc:`/how_to_guides/dumping_transformation` + * :doc:`/how_to_guides/jq_inspection` .. TODO: add the gather, load results, cinnabar and openfe_analysis how-tos. diff --git a/docs/guide/results/simulation_health.rst b/docs/guide/results/simulation_health.rst index f7a662766..6ce90c987 100644 --- a/docs/guide/results/simulation_health.rst +++ b/docs/guide/results/simulation_health.rst @@ -454,7 +454,7 @@ Some problems only show up across a network. Relative free energies around a cycle should sum to zero within their uncertainties, and each edge should agree with the value implied by the rest of the network. Large deviations point to unreliable edges worth checking with the diagnostics above. These checks need a network with redundant edges -(see :doc:`Generate ligand networks `). +(see :doc:`Generate ligand networks `). To calculate cycle closure errors, see the `cinnabar cycle closure tutorial `_. diff --git a/docs/guide/setup/index.rst b/docs/guide/setup/index.rst index 7741cc186..885c6d5f6 100644 --- a/docs/guide/setup/index.rst +++ b/docs/guide/setup/index.rst @@ -47,22 +47,22 @@ See :ref:`dumping transformations ` for more details. **Setup** - * :doc:`/cookbook/loading_molecules` - * :doc:`/cookbook/user_charges` - * :doc:`/cookbook/bespoke_parameters` + * :doc:`/how_to_guides/loading_molecules` + * :doc:`/how_to_guides/user_charges` + * :doc:`/how_to_guides/bespoke_parameters` **Planning: Ligand networks** - * :doc:`/cookbook/generate_ligand_network` - * :doc:`/cookbook/hand_write_ligand_network` - * :doc:`/cookbook/network_from_orion_fepp` - * :doc:`/cookbook/ligandnetwork_vis` - * :doc:`/cookbook/repairing_broken_networks` + * :doc:`/how_to_guides/generate_ligand_network` + * :doc:`/how_to_guides/hand_write_ligand_network` + * :doc:`/how_to_guides/network_from_orion_fepp` + * :doc:`/how_to_guides/ligandnetwork_vis` + * :doc:`/how_to_guides/repairing_broken_networks` **Planning: Protocols and alchemical networks** - * :doc:`/cookbook/choose_protocol` - * :doc:`/cookbook/rfe_alchemical_planners` - * :doc:`/cookbook/create_alchemical_network` + * :doc:`/how_to_guides/choose_protocol` + * :doc:`/how_to_guides/rfe_alchemical_planners` + * :doc:`/how_to_guides/create_alchemical_network` .. TODO: add the new Setup and Planning how-tos to this box as they are added. diff --git a/docs/cookbook/bespoke_parameters.nblink b/docs/how_to_guides/bespoke_parameters.nblink similarity index 100% rename from docs/cookbook/bespoke_parameters.nblink rename to docs/how_to_guides/bespoke_parameters.nblink diff --git a/docs/cookbook/choose_protocol.nblink b/docs/how_to_guides/choose_protocol.nblink similarity index 100% rename from docs/cookbook/choose_protocol.nblink rename to docs/how_to_guides/choose_protocol.nblink diff --git a/docs/cookbook/create_alchemical_network.nblink b/docs/how_to_guides/create_alchemical_network.nblink similarity index 100% rename from docs/cookbook/create_alchemical_network.nblink rename to docs/how_to_guides/create_alchemical_network.nblink diff --git a/docs/cookbook/dumping_transformation.rst b/docs/how_to_guides/dumping_transformation.rst similarity index 100% rename from docs/cookbook/dumping_transformation.rst rename to docs/how_to_guides/dumping_transformation.rst diff --git a/docs/cookbook/generate_ligand_network.nblink b/docs/how_to_guides/generate_ligand_network.nblink similarity index 100% rename from docs/cookbook/generate_ligand_network.nblink rename to docs/how_to_guides/generate_ligand_network.nblink diff --git a/docs/cookbook/hand_write_ligand_network.nblink b/docs/how_to_guides/hand_write_ligand_network.nblink similarity index 100% rename from docs/cookbook/hand_write_ligand_network.nblink rename to docs/how_to_guides/hand_write_ligand_network.nblink diff --git a/docs/cookbook/index.rst b/docs/how_to_guides/index.rst similarity index 100% rename from docs/cookbook/index.rst rename to docs/how_to_guides/index.rst diff --git a/docs/cookbook/jq_inspection.rst b/docs/how_to_guides/jq_inspection.rst similarity index 100% rename from docs/cookbook/jq_inspection.rst rename to docs/how_to_guides/jq_inspection.rst diff --git a/docs/cookbook/ligandnetwork_vis.nblink b/docs/how_to_guides/ligandnetwork_vis.nblink similarity index 100% rename from docs/cookbook/ligandnetwork_vis.nblink rename to docs/how_to_guides/ligandnetwork_vis.nblink diff --git a/docs/cookbook/loading_molecules.nblink b/docs/how_to_guides/loading_molecules.nblink similarity index 100% rename from docs/cookbook/loading_molecules.nblink rename to docs/how_to_guides/loading_molecules.nblink diff --git a/docs/cookbook/network_from_orion_fepp.nblink b/docs/how_to_guides/network_from_orion_fepp.nblink similarity index 100% rename from docs/cookbook/network_from_orion_fepp.nblink rename to docs/how_to_guides/network_from_orion_fepp.nblink diff --git a/docs/cookbook/packmol_memgen_setup.nblink b/docs/how_to_guides/packmol_memgen_setup.nblink similarity index 100% rename from docs/cookbook/packmol_memgen_setup.nblink rename to docs/how_to_guides/packmol_memgen_setup.nblink diff --git a/docs/cookbook/repairing_broken_networks.nblink b/docs/how_to_guides/repairing_broken_networks.nblink similarity index 100% rename from docs/cookbook/repairing_broken_networks.nblink rename to docs/how_to_guides/repairing_broken_networks.nblink diff --git a/docs/cookbook/resume_quickrun.rst b/docs/how_to_guides/resume_quickrun.rst similarity index 100% rename from docs/cookbook/resume_quickrun.rst rename to docs/how_to_guides/resume_quickrun.rst diff --git a/docs/cookbook/rfe_alchemical_planners.nblink b/docs/how_to_guides/rfe_alchemical_planners.nblink similarity index 100% rename from docs/cookbook/rfe_alchemical_planners.nblink rename to docs/how_to_guides/rfe_alchemical_planners.nblink diff --git a/docs/cookbook/run_on_slurm.rst b/docs/how_to_guides/run_on_slurm.rst similarity index 100% rename from docs/cookbook/run_on_slurm.rst rename to docs/how_to_guides/run_on_slurm.rst diff --git a/docs/cookbook/run_quickrun.rst b/docs/how_to_guides/run_quickrun.rst similarity index 100% rename from docs/cookbook/run_quickrun.rst rename to docs/how_to_guides/run_quickrun.rst diff --git a/docs/cookbook/run_repeats_in_parallel.rst b/docs/how_to_guides/run_repeats_in_parallel.rst similarity index 100% rename from docs/cookbook/run_repeats_in_parallel.rst rename to docs/how_to_guides/run_repeats_in_parallel.rst diff --git a/docs/cookbook/run_task_based.rst b/docs/how_to_guides/run_task_based.rst similarity index 100% rename from docs/cookbook/run_task_based.rst rename to docs/how_to_guides/run_task_based.rst diff --git a/docs/cookbook/run_with_mps.rst b/docs/how_to_guides/run_with_mps.rst similarity index 100% rename from docs/cookbook/run_with_mps.rst rename to docs/how_to_guides/run_with_mps.rst diff --git a/docs/cookbook/user_charges.nblink b/docs/how_to_guides/user_charges.nblink similarity index 100% rename from docs/cookbook/user_charges.nblink rename to docs/how_to_guides/user_charges.nblink diff --git a/docs/index.rst b/docs/index.rst index 9366a5386..465b46839 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,7 +39,7 @@ The **OpenFE** ecosystem is a free and open-source framework for planning, runni installation guide/index tutorials/index - cookbook/index + how_to_guides/index reference/index CHANGELOG From 2311b4cb2a161ad4f454dd6e31163beff925c1b3 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 6 Nov 2026 13:22:52 +0100 Subject: [PATCH 2/2] some more changes --- docs/guide/setup/alchemical_network_model.rst | 4 ++-- docs/guide/setup/creating_ligand_networks.rst | 2 +- docs/guide/setup/input_preparation.rst | 6 +++--- docs/how_to_guides/index.rst | 2 +- docs/tutorials/index.rst | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guide/setup/alchemical_network_model.rst b/docs/guide/setup/alchemical_network_model.rst index 615ecbea1..8286d49a4 100644 --- a/docs/guide/setup/alchemical_network_model.rst +++ b/docs/guide/setup/alchemical_network_model.rst @@ -43,14 +43,14 @@ is often done through a :class:`.LigandNetwork`. You can manually create a :class:`.AlchemicalNetwork` by creating a list of :class:`.Transformation` objects. For examples using the Python API, -see :ref:`cookbook on creating alchemical networks `. +see :ref:`How-to guide on creating alchemical networks `. 2. Python ``NetworkPlanner`` Convenience Classes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ OpenFE also provides the convenience classes :class:`.RBFEAlchemicalNetworkPlanner` and :class:`.RHFEAlchemicalNetworkPlanner`, which use the :class:`.RelativeHybridTopologyProtocol` for creating :class:`.AlchemicalNetwork`\s. -For example usage of these convenience classes, see :ref:`Relative Alchemical Network Planners cookbook `. +For example usage of these convenience classes, see :ref:`Relative Alchemical Network Planners How-to guide `. .. note:: The Network Planners are provided for user convenience. While they cover diff --git a/docs/guide/setup/creating_ligand_networks.rst b/docs/guide/setup/creating_ligand_networks.rst index 5f6d96ff8..620a1fc98 100644 --- a/docs/guide/setup/creating_ligand_networks.rst +++ b/docs/guide/setup/creating_ligand_networks.rst @@ -44,7 +44,7 @@ Generating Ligand Networks # plan the ligand network ligand_network = network_planner(ligands=mols, mappers=[mapper], scorer=scorer) -Practical information on generating ligand networks can be found in our :ref:`cookbook for ligand network generation `. +Practical information on generating ligand networks can be found in our :ref:`How-to guide for ligand network generation `. .. note:: Like the Component objects, a ``LigandNetwork`` object is immutable once created! diff --git a/docs/guide/setup/input_preparation.rst b/docs/guide/setup/input_preparation.rst index 127067e35..48ab8dfba 100644 --- a/docs/guide/setup/input_preparation.rst +++ b/docs/guide/setup/input_preparation.rst @@ -82,7 +82,7 @@ The inputs are loaded as follows: * **Pre-solvated systems:** ``SolvatedPDBComponent.from_pdb_file`` or ``ProteinMembraneComponent.from_pdb_file``. - See :doc:`Loading Molecules and Chemical Systems ` for examples. + See :doc:`Loading Molecules and Chemical Systems ` for examples. .. _prep_protein: @@ -180,7 +180,7 @@ results. Partial charges are assigned during protocol setup but can also be assigned in advance for reproducibility and to avoid repeated calculations. -See :doc:`Assigning partial charges ` (Python API) or +See :doc:`Assigning partial charges ` (Python API) or :doc:`Generating Partial Charges with the OpenFE CLI `. .. rubric:: Binding poses @@ -225,7 +225,7 @@ Checklist for preparing input ``Components`` See also -------- -* :doc:`Loading Molecules and Chemical Systems ` +* :doc:`Loading Molecules and Chemical Systems ` * :doc:`Components, Chemical Systems and Thermodynamic Cycles ` * :doc:`Membrane RBFE tutorial ` * :ref:`Protocols and domain of applicability ` \ No newline at end of file diff --git a/docs/how_to_guides/index.rst b/docs/how_to_guides/index.rst index 2e0bdbb14..970218c62 100644 --- a/docs/how_to_guides/index.rst +++ b/docs/how_to_guides/index.rst @@ -1,4 +1,4 @@ -.. _cookbooks: +.. _how_to_guides: How-To Guides ============= diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 8727cb115..7ff721342 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -46,7 +46,7 @@ Post-Simulation Analysis Generating Partial Charges -------------------------- -.. todo: this should be in cookbook +.. todo: this should be in how_to_guides - :ref:`Generating Partial Charges CLI tutorial `: how to use the CLI to assign and store partial charges for mall molecules which can be used throughout the OpenFE ecosystem.