From ed716ee9ca0781195524c8294ec9d83351c47d90 Mon Sep 17 00:00:00 2001
From: Mathieu Doucet <matd10@yahoo.com>
Date: Wed, 11 Sep 2024 12:00:28 -0400
Subject: [PATCH] add docs

---
 README.md                            |  2 --
 docs/how-to-contribute.md            | 51 ++++++++++++++++++++++++++++
 docs/index.rst                       |  1 +
 src/refl1d_models/hydration_model.py | 12 +++++--
 4 files changed, 62 insertions(+), 4 deletions(-)
 create mode 100644 docs/how-to-contribute.md

diff --git a/README.md b/README.md
index e343cab..08019d1 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,6 @@
 <!-- Badges -->
 
 ![Test Status](https://github.com/reflectometry/refl1d_models/actions/workflows/unittest.yml/badge.svg)
-![Packaging Status](https://github.com/reflectometry/refl1d_models/actions/workflows/package.yml/badge.svg)
-
 [![Documentation Status](https://readthedocs.org/projects/refl1d-models/badge/?version=latest)](https://refl1d-models.readthedocs.io/en/latest/?badge=latest)
 
 <!-- End Badges -->
diff --git a/docs/how-to-contribute.md b/docs/how-to-contribute.md
new file mode 100644
index 0000000..aac4ac7
--- /dev/null
+++ b/docs/how-to-contribute.md
@@ -0,0 +1,51 @@
+
+How to submit a model example
+=============================
+
+Submitting your model examples will help the community understand how
+to use refl1d!
+
+Models are useful when they are annotated, and if they are accompanied by example data. You can submit data in any format that you can read in your model script.
+
+The following is an example of how one might structure a submitted model:
+
+```python
+"""
+Model description
+
+Describe your model and what it unique about it.
+"""
+
+import numpy as np
+from refl1d.names import SLD, Experiment, FitProblem, Parameter, QProbe
+
+#####################################################################
+# Probe: this is where you also load your data and define your probe.
+q = np.logspace(np.log10(0.009), np.log10(0.18), num=150)
+dq = 0.025 * q / 2.35
+
+probe = QProbe(q, dq)
+
+#####################################################################
+# Materials: this is where you define your materials
+silicon = SLD(name="Si", rho=2.07, irho=0.0)
+d2o = SLD(name="D2O", rho=6.13, irho=0.0)
+
+#####################################################################
+# Sample: This is where you define your film structure
+sample = ( d2o(0, 5) | silicon )
+
+#####################################################################
+# This is where you define your fit parameters and constraints
+probe.intensity = Parameter(value=1.0, name="normalization")
+probe.background.range(0.0, 1e-05)
+sample["D2O"].interface.range(25.0, 150.0)
+
+# Create the experiment and the problem objects
+experiment = Experiment(probe=probe, sample=sample)
+problem = FitProblem(experiment)
+```
+
+You can either send your model and data to us be email, or create
+a pull request. Creating a pull requests is preferred and will ensure
+a speedier response.
diff --git a/docs/index.rst b/docs/index.rst
index 5388370..09c2e71 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,3 +7,4 @@ Refl1d example models
    :caption: Contents:
 
    README
+   how-to-contribute
diff --git a/src/refl1d_models/hydration_model.py b/src/refl1d_models/hydration_model.py
index 129e4b8..0faedb9 100644
--- a/src/refl1d_models/hydration_model.py
+++ b/src/refl1d_models/hydration_model.py
@@ -1,11 +1,19 @@
 """
-Hydration model example
+Hydration model example. This model shows an example of a film with a solvent
+penetrating into the surface layer. The SLD of the surface layer is a linear
+combination of the SLD of the base material and the solvent, according to a
+hydration parameter.
+
+$$ \rho_{top} = (1 - f) \rho_{base} + f \rho_{solvent} $$
+
+where $f$ is the hydration parameter.
 """
 
 import numpy as np
 from refl1d.names import SLD, Experiment, FitProblem, Parameter, QProbe
 
-# PRobe ########################################################################
+# Probe ########################################################################
+# This is where you also load your data
 q = np.logspace(np.log10(0.009), np.log10(0.18), num=150)
 dq = 0.025 * q / 2.35