docs: reread and fix documentation

README.md

@@ -25,7 +25,7 @@ For an overview of **upcoming releases and planned functionality**, see
 [here](https://github.com/ComPWA/qrules/milestones?direction=asc&sort=title&state=open).
 
 QRules originates from the
-[`expertsystem`](https://pypi.org/project/expertsystem)
+[`expertsystem`](https://pypi.org/project/expertsystem).
 
 ## Available features
 

docs/index.md

@@ -17,13 +17,15 @@ QRules originates from its {mod}`~expertsystem.reaction` module.
 :::
 
 QRules is a system for validating and generating particle reactions, using
-quantum number conservation rules. The user only has to provide a basic
-information of the particle reaction, such as an initial state and a final
-state. Helper functions provide easy ways to configure the system, but the user
-still has full control. QRules then constructs several hypotheses for what
-happens during the transition from initial to final state.
+quantum number conservation rules. The user only has to provide some basic
+information about the particle reaction, such as an initial state and a final
+state.
 
-The {doc}`usage` pages illustrate some of the cool features of {mod}`qrules`.
+Helper functions provide easy and quick ways to configure the system. QRules
+then constructs several hypotheses for what happens during the transition from
+initial to final state.
+
+The {doc}`/usage` pages illustrate some of the cool features of {mod}`qrules`.
 You can run each of them as Jupyter notebooks with the {fa}`rocket` launch
 button in the top-right corner. Enjoy!
 
@@ -38,42 +40,51 @@ QRules consists of three major components:
    A {class}`.StateTransitionGraph` is a
    [directed graph](https://en.wikipedia.org/wiki/Directed_graph) that consists
    of **nodes** and **edges**. In a directed graph, each edge must be connected
-   to at least one node (in correspondence to Feynman graphs). This way, a
-   graph describes the transition from one state to another.
+   to at least one node (in correspondence to
+   [Feynman graphs](https://en.wikipedia.org/wiki/Feynman_diagram)). This way,
+   a graph describes the transition from one state to another.
 
-   - The edges correspond to particles/states, in other words a collection of
-     properties such as the quantum numbers that characterize the particle
-     state.
+   - **Edges** correspond to states (particles with spin). In other words,
+     edges are a collection of properties such as the quantum numbers that
+     characterize a state that the particle is in.
 
-   - Each node represents an interaction and contains all information for the
+   - **Nodes** represents interactions and contain all information for the
      transition of this specific step. Most importantly, a node contains a
      collection of conservation rules that have to be satisfied. An interaction
      node has $M$ ingoing lines and $N$ outgoing lines, where
      $M,N \in \mathbb{Z}$, $M > 0, N > 0$.
 
 2. **Conservation rules**
 
-   The central component are the
-   {mod}`conservation rules <.conservation_rules>`. They belong to individual
-   nodes and receive properties about the node itself, as well as properties of
-   the ingoing and outgoing edges of that node. Based on those properties the
-   conservation rules determine whether edges pass or not.
+   The central component are the {mod}`.conservation_rules`. They belong to
+   individual nodes and receive properties about the node itself, as well as
+   properties of the ingoing and outgoing edges of that node. Based on those
+   properties the conservation rules determine whether edges pass or not.
 
 3. **Solvers**
 
    The determination of the correct state properties in the graph is done by
    solvers. New properties are set for intermediate edges and interaction nodes
    and their validity is checked with the conservation rules.
 
+:::{margin}
+
+The main solver used by {mod}`qrules` is the
+[`constraint`](https://labix.org/doc/constraint) package for the
+[Constraint Satisfaction Problem](https://en.wikipedia.org/wiki/Constraint_satisfaction_problem)
+(CSP).
+
+:::
+
 ```{rubric} QRules workflow
 
 ```
 
 1. **Preparation**
 
    1.1. Build all possible topologies. A **topology** is represented by a
-   {ref}`graph <index:1. State Transition Graphs>`, in which the edges and
-   nodes are empty (no particle information).
+   {class}`.StateTransitionGraph`, in which the edges and nodes are empty (no
+   particle information).
 
    1.2. Fill the topology graphs with the user provided information. Typically
    these are the graph's ingoing edges (initial state) and outgoing edges

docs/install.md

@@ -8,19 +8,30 @@ python3 -m pip install qrules
 
 This installs the [latest, stable release](https://pypi.org/project/qrules)
 that you can find on the
-[`stable`](https://github.com/ComPWA/qrules/tree/stable) branch. The latest
-version on the [`main`](https://github.com/ComPWA/qrules/tree/main) branch can
-be installed as follows:
+[`stable`](https://github.com/ComPWA/qrules/tree/stable) branch.
+
+The latest version on the [`main`](https://github.com/ComPWA/qrules/tree/main)
+branch can be installed as follows:
 
 ```shell
 python3 -m pip install git+https://github.com/ComPWA/qrules@main
 ```
 
-In that case, however, we highly recommend using the more dynamic,
+In that case, however, we highly recommend using the more dynamic
 {ref}`'editable installation' <pwa:develop:Editable installation>` instead.
 This goes as follows:
 
-1. Get the source code (see {doc}`pwa:software/git`):
+:::{margin}
+
+```{seealso}
+
+{doc}`pwa:software/git`
+
+```
+
+:::
+
+1. Get the source code:
 
    ```shell
    git clone https://github.com/ComPWA/qrules.git
@@ -30,16 +41,16 @@ This goes as follows:
 2. **[Recommended]** Create a virtual environment (see
    {ref}`here <pwa:develop:Virtual environment>`).
 
-3. Install the project in
-   {ref}`'editable installation' <pwa:develop:Editable installation>`, as well
-   as {ref}`optional dependencies <pwa:develop:Optional dependencies>` for the
-   developer:
+3. Install the project as an
+   {ref}`'editable installation' <pwa:develop:Editable installation>` and
+   install {ref}`additional packages <pwa:develop:Optional dependencies>` for
+   the developer:
 
    ```shell
    python3 -m pip install -e .[dev]
    ```
 
-   :::{dropdown} Pinning dependencies
+   :::{dropdown} Pinning dependency versions
 
    In order to install the _exact same versions_ of the dependencies with which
    the framework has been tested, use the provided
@@ -50,8 +61,14 @@ This goes as follows:
    python3 -m pip install -c .constraints/py3.x.txt -e .[dev]
    ```
 
+   ```{seealso}
+
+   {ref}`develop:Pinning dependency versions`
+
+   ```
+
    :::
 
-That's all! Have a look at the {doc}`/usage` page to try out the package, and
-see {doc}`pwa:develop` for tips on how to work with this 'editable' developer
-setup!
+That's all! Have a look at the {doc}`/usage` page to try out the package. You
+can also have a look at the {doc}`pwa:develop` page for tips on how to work
+with this 'editable' developer setup!

docs/usage.ipynb

@@ -58,7 +58,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Here's a small example of how to use {mod}`qrules`!"
+    "Here are some quick examples of how to use {mod}`qrules`. For more fine-grained control, have a look at {ref}`usage:Advanced`."
    ]
   },
   {
@@ -113,7 +113,7 @@
    "source": [
     ":::{seealso}\n",
     "\n",
-    "{doc}`usage/reaction` and {doc}`usage/amplitude`\n",
+    "{doc}`/usage/reaction` and {doc}`ampform:usage/amplitude`\n",
     "\n",
     ":::"
    ]
@@ -152,9 +152,8 @@
     "import qrules as q\n",
     "\n",
     "pdg = q.load_pdg()\n",
-    "pdg.find(22)\n",
-    "delta = pdg.find(\"Delta(1920)++\")\n",
-    "q.io.asdict(delta)"
+    "pdg.find(22)  # by pid\n",
+    "pdg.find(\"Delta(1920)++\")"
    ]
   },
   {

docs/usage/particle.ipynb

@@ -57,7 +57,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In {doc}`reaction`, we made use of the {class}`.StateTransitionManager`. By default, if you do not specify the `particle_db` argument, the {class}`.StateTransitionManager` calls the function {func}`.load_default_particles`. This functions returns a {class}`.ParticleCollection` instance with {class}`.Particle` definitions from the [PDG](https://pdg.lbl.gov), along with additional definitions that are provided in the file {download}`additional_definitions.yml <../../src/qrules/additional_definitions.yml>`.\n",
+    "In {doc}`/usage/reaction`, we made use of the {class}`.StateTransitionManager`. By default, if you do not specify the `particle_db` argument, the {class}`.StateTransitionManager` calls the function {func}`.load_default_particles`. This functions returns a {class}`.ParticleCollection` instance with {class}`.Particle` definitions from the [PDG](https://pdg.lbl.gov), along with additional definitions that are provided in the file {download}`additional_definitions.yml <../../src/qrules/additional_definitions.yml>`.\n",
     "\n",
     "Here, we call this method directly to illustrate what happens (we use {func}`.load_pdg`, which loads a subset):"
    ]

docs/usage/reaction.ipynb

@@ -47,7 +47,7 @@
     "\n",
     "The [‘expert system’](https://en.wikipedia.org/wiki/Expert_system) is responsible to give you advice on the form of an amplitude model, based on the problem set you define (initial state, final state, allowed interactions, intermediate states, etc.). Internally, the system propagates the quantum numbers through the reaction graph while satisfying the specified conservation rules. How to control this procedure is explained in more detail below.\n",
     "\n",
-    "Afterwards, the amplitude model of the expert system can be exported into [Tensorwaves](https://pwa.readthedocs.io/projects/tensorwaves). The model can for instance be used to generate a data set (toy Monte Carlo) for this reaction and to optimize its parameters to resemble an actual data set as good as possible. For more info on that see {doc}`expertsystem:usage/amplitude`."
+    "Afterwards, the amplitude model of the expert system can be exported into [Tensorwaves](https://pwa.readthedocs.io/projects/tensorwaves). The model can for instance be used to generate a data set (toy Monte Carlo) for this reaction and to optimize its parameters to resemble an actual data set as good as possible. For more info on that see {doc}`ampform:usage/amplitude`."
    ]
   },
   {
@@ -424,7 +424,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Handy if it takes a lot of computation time to generate the transitions!"
+    "Handy if it takes a lot of computation time to re-generate the transitions!"
    ]
   },
   {
@@ -441,7 +441,7 @@
    "metadata": {},
    "source": [
     "```{tip}\n",
-    "The {mod}`ampform` package can formulate amplitude models based on the state transitions created by {mod}`qrules`.\n",
+    "The {mod}`ampform` package can formulate amplitude models based on the state transitions created by {mod}`qrules`. See {doc}`ampform:usage/amplitude`.\n",
     "```"
    ]
   }

docs/usage/visualize.ipynb

@@ -43,7 +43,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The {mod}`~qrules.io` module allows you to convert {class}`.StateTransitionGraph` and {class}`.Topology` instances to [DOT language](https://graphviz.org/doc/info/lang.html) with {func}`.asdot`. You can visualize its output with third-party libraries, such as [Graphviz](https://graphviz.org). This is particularly useful after running {meth}`~.StateTransitionManager.find_solutions`, which produces a {class}`.Result` object with a {class}`.list` of {class}`.StateTransitionGraph` instances (see {doc}`reaction`)."
+    "The {mod}`~qrules.io` module allows you to convert {class}`.StateTransitionGraph` and {class}`.Topology` instances to [DOT language](https://graphviz.org/doc/info/lang.html) with {func}`.asdot`. You can visualize its output with third-party libraries, such as [Graphviz](https://graphviz.org). This is particularly useful after running {meth}`~.StateTransitionManager.find_solutions`, which produces a {class}`.Result` object with a {class}`.list` of {class}`.StateTransitionGraph` instances (see {doc}`/usage/reaction`)."
    ]
   },
   {