Add getting started docs

docs/getting_started.rst

@@ -1,28 +1,101 @@
-:orphan:
-
-.. # remove "orphan" once this has been populated
-
 Getting started using Lomap
 ===========================
 
-introduction to Lomap
+Lomap plans networks of relative free energy calculations across a set of
+ligands. Its interface provides
+`gufe <https://gufe.openfree.energy/en/latest/>`_ bindings, so Lomap's atom
+mapping, scoring, and network planning interoperate with the rest of the
+`Open Free Energy <https://openfree.energy>`_ ecosystem. The workflow is:
+load your ligands, propose atom mappings between them, score
+those mappings, and assemble them into a network. Each step is available on its
+own, but most users only need :func:`~lomap.generate_lomap_network`, covered at
+the end of this guide.
+
+These bindings require the optional ``gufe`` dependency
+(see :doc:`installation`).
+
+All examples below use these two example ligands:
+
+.. code-block:: python
+
+    import importlib.resources
+
+    from gufe import SmallMoleculeComponent
+
+    data = importlib.resources.files("lomap.tests.data")
+    ligands = [
+        SmallMoleculeComponent.from_sdf_file(data / name)
+        for name in ["lig_41.sdf", "lig_74.sdf"]
+    ]
 
 Generating mappings
 -------------------
 
-how to generate mappings
+A :class:`~lomap.LomapAtomMapper` proposes an atom mapping between a pair of
+ligands. ``suggest_mappings`` yields ``LigandAtomMapping`` objects, or nothing
+if the ligands share no suitable common substructure.
+
+.. code-block:: python
+
+    from lomap import LomapAtomMapper
+
+    mapper = LomapAtomMapper()
+    mappings = list(mapper.suggest_mappings(ligands[0], ligands[1]))
+
+    mapping = mappings[0]
+
+    # atom indices in ligand A mapped onto the corresponding atoms in ligand B
+    print(mapping.componentA_to_componentB)
+
+The mapper can be tuned with options such as ``time``,
+``threed``, ``max3d``, ``element_change``, ``seed``, and ``shift``. See the
+:ref:`API reference <gufe bindings api>` for details.
 
 Generating scores
 -----------------
 
-giving scores to mappings
+A scorer takes a ``LigandAtomMapping`` and returns a value from ``0.0`` (worst)
+to ``1.0`` (best).
+:func:`~lomap.default_lomap_score` is the standard Lomap
+score, a product of sub-scores penalizing changes such as broken rings, altered
+ring sizes, and net-charge differences.
+
+.. code-block:: python
+
+    from lomap import default_lomap_score
+
+    score = default_lomap_score(mapping)
+    print(f"{score:.3f}")
+
+The sub-scores live in ``lomap.gufe_bindings.scorers`` if you need a custom
+scorer.
 
 Generating networks
 -------------------
 
-planning entire networks
+:func:`~lomap.generate_lomap_network` combines the previous steps. Given a set of ligands, a
+mapper, and a scorer, it proposes and scores edges and assembles a connected
+``LigandNetwork``.
+
+.. code-block:: python
+
+    from lomap import LomapAtomMapper, default_lomap_score, generate_lomap_network
+
+    network = generate_lomap_network(
+        ligands=ligands,
+        mappers=LomapAtomMapper(),
+        scorer=default_lomap_score,
+    )
+
+    print(f"{len(network.nodes)} ligands, {len(network.edges)} edges")
+
+``network.nodes`` are the ligands and ``network.edges`` the scored mappings.
+Options such as ``distance_cutoff``, ``require_cycle_covering``, and ``radial``
+are documented in the :ref:`API reference <gufe bindings api>`.
 
 Command line interface
 ----------------------
 
-using the command line interface
+The legacy ``lomap`` command-line tool is deprecated and will be removed in the
+next major release; use :func:`~lomap.generate_lomap_network` instead. See
+:doc:`legacy`.

docs/index.rst

@@ -13,6 +13,7 @@ Lomap (Lead Optimization Mapper) is a tool for planning perturbation networks fo
    :caption: Contents:
 
    installation.rst
+   getting_started.rst
    api.rst
    legacy.rst
    citing.rst