diff --git a/hugo/content/py/ex/_index.md b/hugo/content/py/ex/_index.md
new file mode 100644
index 0000000000000000000000000000000000000000..b9e46341965757f7d47b4f9367e43f9c76fb503b
--- /dev/null
+++ b/hugo/content/py/ex/_index.md
@@ -0,0 +1,8 @@
++++
+title = "Examples"
+weight = 5
++++
+
+## Commented Python script examples
+
+{{% children %}}
\ No newline at end of file
diff --git a/hugo/content/py/sim/gisas/no-dwba-terms/CylindersInBA_setup.jpg b/hugo/content/py/ex/gisas-no-dwba-terms/CylindersInBA_setup.jpg
similarity index 100%
rename from hugo/content/py/sim/gisas/no-dwba-terms/CylindersInBA_setup.jpg
rename to hugo/content/py/ex/gisas-no-dwba-terms/CylindersInBA_setup.jpg
diff --git a/hugo/content/py/sim/gisas/no-dwba-terms/index.md b/hugo/content/py/ex/gisas-no-dwba-terms/index.md
similarity index 97%
rename from hugo/content/py/sim/gisas/no-dwba-terms/index.md
rename to hugo/content/py/ex/gisas-no-dwba-terms/index.md
index f294c41d11aad58f1c62d9a9d010907c0ca2e9a6..b7390573b0a14f17786220471c06d690376422f0 100644
--- a/hugo/content/py/sim/gisas/no-dwba-terms/index.md
+++ b/hugo/content/py/ex/gisas-no-dwba-terms/index.md
@@ -9,7 +9,7 @@ This example shows scattering
 from a monolayer that contains a dilute random assembly
 of monodisperse cylindrical disks.
 
-This is the same system as in our [basic GISAS example]({{% ref-py "sim/gisas" %}})
+This is the same system as in our [basic GISAS example]({{% ref-py "ex/gisas" %}})
 except that there is no substrate.
 In consequence, there are no reflections,
 and therefore the DWBA boils down to the ordinary Born approximation.
diff --git a/hugo/content/py/sim/gisas/CylindersInDWBA_setup.jpg b/hugo/content/py/ex/gisas/CylindersInDWBA_setup.jpg
similarity index 100%
rename from hugo/content/py/sim/gisas/CylindersInDWBA_setup.jpg
rename to hugo/content/py/ex/gisas/CylindersInDWBA_setup.jpg
diff --git a/hugo/content/py/sim/gisas/_index.md b/hugo/content/py/ex/gisas/_index.md
similarity index 100%
rename from hugo/content/py/sim/gisas/_index.md
rename to hugo/content/py/ex/gisas/_index.md
diff --git a/hugo/content/py/sim/sas/_index.md b/hugo/content/py/ex/sas/_index.md
similarity index 100%
rename from hugo/content/py/sim/sas/_index.md
rename to hugo/content/py/ex/sas/_index.md
diff --git a/hugo/content/py/sim/sas/polarized/index.md b/hugo/content/py/ex/sas/polarized/index.md
similarity index 100%
rename from hugo/content/py/sim/sas/polarized/index.md
rename to hugo/content/py/ex/sas/polarized/index.md
diff --git a/hugo/content/py/fitting/gisas-fit2d/index.md b/hugo/content/py/fitting/gisas-fit2d/index.md
index 28ac5a22d1846f8ec206647f41f8a665e851d5d6..fdfffc1568681ed67c68c881a3a296911d4be383 100644
--- a/hugo/content/py/fitting/gisas-fit2d/index.md
+++ b/hugo/content/py/fitting/gisas-fit2d/index.md
@@ -10,7 +10,7 @@ This example demonstrates fitting of 2D GISAS data.
 ## Faked experimental data
 
 The sample and instrument model is basically the same as
-in our [basic GISAS simulation example]({{% ref-py "sim/gisas" %}}),
+in our [basic GISAS simulation example]({{% ref-py "ex/gisas" %}}),
 except that it depends on four external parameters:
 beam intensity, detector background, radius and height of the cylindrical nanoparticles.
 
@@ -44,7 +44,7 @@ and terminates with the following result:
 ### Explanation
 
 The function `get_sample` is basically the same as
-in our [basic GISAS simulation example]({{% ref-py "sim/gisas" %}}),
+in our [basic GISAS simulation example]({{% ref-py "ex/gisas" %}}),
 except that radius and height of the cylindrical disks are now
 supplied as external parameters.
 These parameters are passed through the function argument `params`
diff --git a/hugo/content/py/instr/det/resolution/index.md b/hugo/content/py/instr/det/resolution/index.md
index 25aac2bee3e14bfdfd94d60f126e28a9b19c1952..3ef13f4c598bfcb52a67fdfb94d0d18196e18208 100644
--- a/hugo/content/py/instr/det/resolution/index.md
+++ b/hugo/content/py/instr/det/resolution/index.md
@@ -13,7 +13,7 @@ Here we show how to set a finite blur.
 * The incident angles are $\sigma_{\alpha\_i} = \sigma\_{\varphi\_i} = 0.1^{\circ}$.
 
 Besides this, the example is a DWBA simulation for our standard sample model,
- [Cylinders in DWBA]({{% ref-py "sim/gisas" %}})
+ [Cylinders in DWBA]({{% ref-py "ex/gisas" %}})
 
 * The sample is composed of monodisperse cylinders deposited on a substrate.
 * The cylinders are dilute, and positioned at random,
diff --git a/hugo/content/py/result/export/axes-in-different-units/index.md b/hugo/content/py/result/export/axes-in-different-units/index.md
index cfde9a94ed0e2521c9997413be8153ef66b333c8..42eb72388c03eea0a14a8605bea7e32f773c9e27 100644
--- a/hugo/content/py/result/export/axes-in-different-units/index.md
+++ b/hugo/content/py/result/export/axes-in-different-units/index.md
@@ -8,7 +8,7 @@ weight = 20
 In this example we demonstrate how to plot intensity data with detector axes expressed in different units. It serves as a supporting example to the
 [Accessing simulation results]({{% ref-py "export/_index.md" %}}) tutorial.
 
-* The standard [Cylinders in DWBA]({{%ref-py "sim/gisas" %}}))
+* The standard [Cylinders in DWBA]({{%ref-py "ex/gisas" %}}))
 sample is used to setup the simulation.
 * When the simulation is completed, the `Simulation::result()` method is used to get a `SimulationResult` object.
 * Depending on an additional parameter `IDetector2D.NBINS`, `IDetector2D.DEGREES`, `IDetector2D.QYQZ`, it will be plotted with axes defined either in millimeters (default units of `RectangularDetector`), detector bins, degrees or in $Q$-space.
diff --git a/hugo/content/py/result/export/more.md b/hugo/content/py/result/export/more.md
index 28823357d4d2fc098304449d27454feb4eeab182..5d6d379a873c598c47898b8d1895dddd0b413102 100644
--- a/hugo/content/py/result/export/more.md
+++ b/hugo/content/py/result/export/more.md
@@ -8,7 +8,7 @@ weight = 10
 This is an extended example for the further treatment of simulation results: accessing the results, plotting, cropping, slicing and exporting. This serves as a supporting example to the [Accessing simulation results
 ]({{% ref-py "export/_index.md" %}}) tutorial.
 
-* The standard [Cylinders in DWBA]({{%ref-py "sim/gisas" %}}) sample
+* The standard [Cylinders in DWBA]({{%ref-py "ex/gisas" %}}) sample
 is used for running the simulation.
 * The simulation results are retrieved as a `Histogram2D` object and then processed in various functions to achieve a resulting image.
 
diff --git a/hugo/content/py/sim/_index.md b/hugo/content/py/sim/_index.md
index e3acae99fdd72c96226ab191fb9ecc4639242577..7a7fca36d8876af45e7a810836aedf3f4e1e5a55 100644
--- a/hugo/content/py/sim/_index.md
+++ b/hugo/content/py/sim/_index.md
@@ -9,7 +9,7 @@ To set up and run a BornAgain simulation, one needs to create an instance of
 a simulation class. This class contains information about the scattering
 target ("sample") and about the simulated instrument (beam or scan, detector).
 
-#### Simulation cclasses
+#### Simulation classes
 
 The following simulation classes are available:
 
diff --git a/hugo/content/py/sim/class/_index.md b/hugo/content/py/sim/class/_index.md
index 1fc41c9d2dd9171322d4af18b78041eadfdc379e..f34befbc453b1e9931f1898484c04462aedad934 100644
--- a/hugo/content/py/sim/class/_index.md
+++ b/hugo/content/py/sim/class/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Simulation classes"
-weight = 0
+weight = 10
 +++
 
 ## Simulation classes
diff --git a/hugo/content/py/sim/class/scattering/index.md b/hugo/content/py/sim/class/scattering/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..2c3ab00f8dfdd88dc073977ef3d5bc49f52cb9bd
--- /dev/null
+++ b/hugo/content/py/sim/class/scattering/index.md
@@ -0,0 +1,25 @@
++++
+title = "Scattering"
+weight = 20
++++
+
+## Scattering simulation
+
+To set up and run a scattering simulation, use
+```python
+import bornagain as ba
+beam = ...
+sample = ...
+detector = ...
+simulation = ba.ScatteringSimulation(beam, sample, detector)
+# ... set options
+result = simulation.simulate()
+```
+
+For the constructor arguments, see sections [beam]({{% ref-py "instr/beam" %}})
+[sample]({{% ref-py "sample" %}}), and [detector](/py/instr/det).
+
+For optional settings, see [simulation options]({{% ref-py "sim/setup/options" %}}).
+
+For the return type of function `simulate()`,
+see [SimulationResult]({{% ref-py "result/simulation-result" %}}).
diff --git a/hugo/content/py/sim/class/specular/_index.md b/hugo/content/py/sim/class/specular/index.md
similarity index 100%
rename from hugo/content/py/sim/class/specular/_index.md
rename to hugo/content/py/sim/class/specular/index.md