fix docs table of contents

README.md

@@ -74,11 +74,13 @@ Notes:
 
 ## Dev Guide - Adding notebooks to Read The Docs
 
-- Copy notebook into `docs/notebooks` (N.B. the notebook must have at least one section header and be using the "Python 3 (ipykernel)" kernel, not some conda env kernel that may only be installed locally)
+- Copy notebook into `docs/notebooks` (N.B. the notebook must have at least one section header* and be using the "Python 3 (ipykernel)" kernel, not some conda env kernel that may only be installed locally)
 - Update the toctree in the file `docs/notebooks.rst`
 - Ensure necessary requirements are declared in `pyproject.toml` and `docs/requirements.txt`. Also, make sure that the notebook being added to the docs is using the python3 (ipykernel) kernel, not some conda env kernel that may only be installed locally
 - To update the docs locally, from the `docs` dir run: `python -m sphinx -T -E -b html -d _build/doctrees -D language=en . ../_readthedocs/html`
 
+* Multiple section headers from a notebook will also show up in the table of contents.
+
 ## Dev Guide - Updating pyproject.toml
 
 If you are adding code that requires a new dependency, this needs to be included in pyproject.toml under the `[project]' section:

docs/index.rst

@@ -5,6 +5,11 @@
 Welcome to adler's documentation!
 ========================================================================================
 
+Introduction
+------------
+
+Adler is an open source package which provides tools for detecting and characterising activity in observations of solar system objects.
+
 Dev Guide - Getting Started
 ---------------------------
 

docs/notebooks/colour_functions_example.ipynb

@@ -5,7 +5,7 @@
    "id": "6ebe3e22",
    "metadata": {},
    "source": [
-    "# Adler running colour measurement\n",
+    "# Adler colour measurement\n",
     "\n",
     "Adler includes a function `col_obs_ref` which calculates the difference between the most recent brightness data point in the observation (obs) filter and a number of previous measurements in the reference (ref) filter."
    ]
@@ -147,7 +147,8 @@
    "id": "e07e86a8",
    "metadata": {},
    "source": [
-    "# Get determine the apparitions (periods of observability) of the object\n",
+    "**Determine the apparitions (periods of observability) of the object.**\n",
+    "\n",
     "Get the boundary times for each apparation of the object in the survey using the Adler helper function `apparition_gap_finder`.\n",
     "In this example we will just look at changes in colour for a single apparition"
    ]

docs/notebooks/outlier_detection_example.ipynb

@@ -164,7 +164,8 @@
    "id": "4318568a",
    "metadata": {},
    "source": [
-    "# return a list of flags for outlying objects\n",
+    "**Return a list of flags for outlying objects.**\n",
+    "\n",
     "The Adler `utils.sigma_clip` function is a wrapper for `astropy.stats.sigma_clip`. We do this in order to return just the clip mask, and also to make it easier to call a \"zero\" central function."
    ]
   },