fix typo in README.md

to dev

.github/workflows/ci-docs.yml

@@ -17,7 +17,7 @@ jobs:
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
       - uses: actions/setup-python@v5
         with:
-          python-version: 3.x
+          python-version: 3.12.9
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:

README.md

@@ -23,13 +23,27 @@ With Python verion `>=3.12.4` and `<3.13`, create a virtual environment and inst
 ```
 python3 -m venv .venv
 source .venv/bin/activate
-(venv) pip install -e .[dev]
+```
+
+With the virtual environment activated, run:
+
+```
+pip install -e .[dev]
 ```
 
 ## Tests
 
-Tests can be run with `pytest` from the root directory of the repository.
+Tests can be run with `pytest` from the root directory of the repository. With the virtual environment activated, run:
 
 ```
-(venv) pytest
+pytest
-```
+```
+
+## Local viewing of documentation
+
+PG-RAD uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) for generating documentation. It can be locally viewed by (in the venv) running:
+```
+mkdocs serve
+```
+
+where you can add the `--livereload` flag to automatically update the documentation as you write to the Markdown files.

docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

docs/pg-rad-in-python.ipynb

@@ -5,14 +5,22 @@
    "id": "5e30f59a",
    "metadata": {},
    "source": [
-    "# Demo of PG-RAD\n",
+    "# Using PG-RAD as a module\n",
     "\n",
-    "This is a demo."
+    "This discusses the overall design of the code to understand how different parts interact, doing so by an interactive notebook demo. For specific usage of functions and classes, consult the API documentation in the side bar (relevant API documentation sections will also be hyperlinked in the below explanation)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f18912e5",
+   "metadata": {},
+   "source": [
+    "## Imports"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 5,
    "id": "415fdd25",
    "metadata": {},
    "outputs": [],
@@ -22,7 +30,7 @@
     "from pg_rad.dataloader import load_data\n",
     "from pg_rad.path import path_from_RT90\n",
     "from pg_rad.landscape import Landscape\n",
-    "from pg_rad.objects import Source\n",
+    "from pg_rad.sources import PointSource\n",
     "\n",
     "from pg_rad.isotope import Isotope"
    ]
@@ -37,7 +45,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 6,
    "id": "5a0e470a",
    "metadata": {},
    "outputs": [],
@@ -56,7 +64,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 7,
    "id": "2ec97553",
    "metadata": {},
    "outputs": [
@@ -64,7 +72,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2026-01-27 20:48:51,754 - INFO: Piecewise regression reduced path from 105 to 4 segments.\n"
+      "2026-01-28 13:31:03,130 - INFO: Piecewise regression reduced path from 105 to 4 segments.\n"
      ]
     },
     {
@@ -79,8 +87,8 @@
     }
    ],
    "source": [
-    "p1 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", simplify_path = False)\n",
+    "p1 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", path_simplify = False)\n",
-    "p2 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", simplify_path = True)\n",
+    "p2 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", path_simplify = True)\n",
     "\n",
     "p1.plot(color='r', linestyle='-', linewidth = 10, label = \"Full path\")\n",
     "p2.plot(color='b', linestyle='-', marker = 'o', label = \"Reduced path\")\n",
@@ -96,14 +104,20 @@
    "id": "da8620fa",
    "metadata": {},
    "source": [
-    "## Making a landscape\n",
+    "## Landscape\n",
     "\n",
-    "You can make a landscape with or without a path. Let's make an empty landscape."
+    "The [Landscape](/API/landscape/landscape) is the starting point for the model. It is essentially an empty data structure which represents a cuboid space\n",
+    "\n",
+    "$$\n",
+    "C = [0, x_{\\max}] \\times [0, y_{\\max}] \\times [0, z_{\\max}] \\subset \\mathbb{R}^3\n",
+    "$$\n",
+    "\n",
+    "where $x_{\\max}, y_{\\max}, z_{\\max}$ are defined by the user upon creating the landscape object."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 8,
    "id": "24f1159d",
    "metadata": {},
    "outputs": [
@@ -119,47 +133,57 @@
     }
    ],
    "source": [
-    "landscape = Landscape()\n",
+    "my_landscape = Landscape(size = (500, 500, 500), scale = 'meters')\n",
-    "fig, ax = landscape.plot()\n",
+    "fig, ax = my_landscape.plot()\n",
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a285a2b6",
+   "metadata": {},
+   "source": [
+    "Not much to see here, but we created the backbone of our simulation now."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "035b4f42",
    "metadata": {},
    "source": [
-    "## Adding a source"
+    "## Point sources\n",
+    "\n",
+    "A [PointSource](/API/sources/point_source) can be added to `my_landscape` in the following way:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 9,
    "id": "91019da5",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[Source(name=Source 1, pos=(100, 100, 0), isotope=Cs137, A=100 MBq)]"
+       "[PointSource(name=Source 1, pos=(100, 100, 0), isotope=Cs137, A=100 MBq)]"
       ]
      },
-     "execution_count": 5,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "cs137 = Isotope(name = \"Cs137\", E = 662.66, b = 0.851)\n",
-    "my_source = Source(x = 100, y = 100, z = 0, activity = 100, isotope = cs137)\n",
+    "my_source = PointSource(x = 100, y = 100, z = 0, activity = 100, isotope = cs137)\n",
-    "landscape.add_sources(my_source)\n",
+    "my_landscape.add_sources(my_source)\n",
     "\n",
-    "landscape.sources"
+    "my_landscape.sources"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 10,
    "id": "7913fe1e",
    "metadata": {},
    "outputs": [
@@ -170,7 +194,7 @@
        " <Axes: xlabel='X [meters]', ylabel='Y [meters]'>)"
       ]
      },
-     "execution_count": 6,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -186,12 +210,12 @@
     }
    ],
    "source": [
-    "landscape.plot()"
+    "my_landscape.plot()"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 11,
    "id": "df4715c1",
    "metadata": {},
    "outputs": [
@@ -202,7 +226,7 @@
        " <Axes: xlabel='X [meters]', ylabel='Y [meters]'>)"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -218,8 +242,8 @@
     }
    ],
    "source": [
-    "landscape.set_path(p2)\n",
+    "my_landscape.set_path(p2)\n",
-    "landscape.plot()"
+    "my_landscape.plot()"
    ]
   },
   {

docs/pg-rad-in-python.md

@@ -1,5 +0,0 @@
----
-title: Using PG-RAD as a module
----
-
-Consult the API documentation in the side bar.

mkdocs.yml

@@ -28,8 +28,15 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
 
 plugins:
+- mkdocs-jupyter
 - mkdocstrings:
     enabled: !ENV [ENABLE_MKDOCSTRINGS, true]
     default_handler: python

pyproject.toml

@@ -29,4 +29,4 @@ Homepage = "https://github.com/pim-n/pg-rad"
 Issues = "https://github.com/pim-n/pg-rad/issues"
 
 [project.optional-dependencies]
-dev = ["pytest", "notebook", "mkdocs-material", "mkdocstrings-python"]
+dev = ["pytest", "notebook", "mkdocs-material", "mkdocstrings-python", "mkdocs-jupyter"]