docs: executed markdown pages for HowToLens Chapter 1 (+ setup_notebook fix)

README.md

@@ -2,6 +2,7 @@
 
 [Installation Guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html) |
 [PyAutoLens readthedocs](https://pyautolens.readthedocs.io/en/latest/index.html) |
+[Browse Chapter 1 With Images](markdown/README.md) |
 [autolens_workspace](https://github.com/PyAutoLabs/autolens_workspace)
 
 <img src="https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautolens.gif?raw=true" width="900" />

config/build/markdown_examples.yaml

@@ -0,0 +1,21 @@
+# Curated examples rendered to executed markdown pages (markdown/) with real
+# output images, for GitHub browsing. Built by PyAutoBuild's generate_markdown.py.
+# Batch 2b: chapter_1_introduction (no non-linear searches — fast).
+- script: scripts/chapter_1_introduction/tutorial_0_visualization.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_2_ray_tracing.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_3_more_ray_tracing.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_4_point_sources.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_5_lensing_formalism.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_6_data.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_7_fitting.py
+  max_minutes: 30
+- script: scripts/chapter_1_introduction/tutorial_8_summary.py
+  max_minutes: 30

markdown/README.md

@@ -0,0 +1,15 @@
+# HowToLens examples, executed — browse with output images
+
+Every page below is the corresponding example script **fully executed**, rendered to markdown with its real output images, so you can read the examples on GitHub exactly as they run. Each page links back to the `.py` script and Jupyter notebook it was generated from.
+
+- [Tutorial 0: Visualization](chapter_1_introduction/tutorial_0_visualization.md) — from `scripts/chapter_1_introduction/tutorial_0_visualization.py`
+- [HowToLens: Introduction](chapter_1_introduction/tutorial_1_grids_and_galaxies.md) — from `scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py`
+- [Tutorial 2: Ray Tracing](chapter_1_introduction/tutorial_2_ray_tracing.md) — from `scripts/chapter_1_introduction/tutorial_2_ray_tracing.py`
+- [Tutorial 5: More Ray Tracing](chapter_1_introduction/tutorial_3_more_ray_tracing.md) — from `scripts/chapter_1_introduction/tutorial_3_more_ray_tracing.py`
+- [Tutorial 4: Point Sources](chapter_1_introduction/tutorial_4_point_sources.md) — from `scripts/chapter_1_introduction/tutorial_4_point_sources.py`
+- [Tutorial 5: Lensing Formalism](chapter_1_introduction/tutorial_5_lensing_formalism.md) — from `scripts/chapter_1_introduction/tutorial_5_lensing_formalism.py`
+- [Tutorial 6: Data](chapter_1_introduction/tutorial_6_data.md) — from `scripts/chapter_1_introduction/tutorial_6_data.py`
+- [Tutorial 7: Fitting](chapter_1_introduction/tutorial_7_fitting.md) — from `scripts/chapter_1_introduction/tutorial_7_fitting.py`
+- [Tutorial 9: Summary](chapter_1_introduction/tutorial_8_summary.md) — from `scripts/chapter_1_introduction/tutorial_8_summary.py`
+
+These pages are regenerated manually by PyAutoBuild's `generate_markdown.py` when a curated script changes.

markdown/chapter_1_introduction/tutorial_0_visualization.md

@@ -0,0 +1,193 @@
+> ✏️ **This page is auto-generated from [`scripts/chapter_1_introduction/tutorial_0_visualization.py`](../../scripts/chapter_1_introduction/tutorial_0_visualization.py) — do not edit it directly.**
+> It shows the example fully executed, with its real output images.
+> Run it yourself via the [Python script](../../scripts/chapter_1_introduction/tutorial_0_visualization.py) or the [Jupyter notebook](../../notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb).
+
+Tutorial 0: Visualization
+=========================
+
+In this tutorial, we quickly cover visualization in **PyAutoLens** and make sure images display
+clearly in your Jupyter notebook and on your computer screen.
+
+__Contents__
+
+- **Directories:** **PyAutoLens assumes** the working directory is `autolens_workspace` on your hard-disk.
+- **Dataset:** Load and plot the strong lens dataset.
+- **Subplots:** In addition to plotting individual figures, **PyAutoLens** can plot `subplots` which show multiple.
+- **Plot Customization:** Does the figure display correctly on your computer screen?
+- **Overlays:** Overlays such as critical curves and image positions are added using the `lines=` and `positions=`.
+- **Wrap Up:** Summary of the script and next steps.
+
+
+```python
+
+from autoconf import jax_wrapper  # Sets JAX environment before other imports
+
+from autoconf import setup_notebook; setup_notebook()
+```
+
+    Working Directory has been set to `HowToLens`
+
+
+If the printed working directory does not match the workspace path on your computer, you can manually set it
+as follows (the example below shows the path I would use on my laptop. The code is commented out so you do not
+use this path in this tutorial!
+
+
+```python
+# workspace_path = "/Users/Jammy/Code/PyAuto/autolens_workspace"
+# #%cd $workspace_path
+# print(f"Working Directory has been set to `{workspace_path}`")
+```
+
+__Dataset__
+
+The `dataset_path` specifies where the dataset is located, which is the
+directory `autolens_workspace/dataset/imaging/simple__no_lens_light`.
+
+There are many example simulated images of strong lenses in this directory that will be used throughout the
+**HowToLens** lectures.
+
+
+```python
+from pathlib import Path
+
+import autolens as al
+import autolens.plot as aplt
+
+dataset_path = Path("dataset") / "imaging" / "simple__no_lens_light"
+```
+
+We now load this dataset from .fits files and create an instance of an `Imaging` object.
+
+
+```python
+dataset = al.Imaging.from_fits(
+    data_path=dataset_path / "data.fits",
+    noise_map_path=dataset_path / "noise_map.fits",
+    psf_path=dataset_path / "psf.fits",
+    pixel_scales=0.1,
+)
+```
+
+We can plot an image with `aplt.plot_array()`, passing the data array and a title.
+
+
+```python
+aplt.plot_array(array=dataset.data, title="Dataset Image")
+```
+
+
+
+![png](tutorial_0_visualization_files/tutorial_0_visualization_9_0.png)
+
+
+
+__Subplots__
+
+In addition to plotting individual figures, **PyAutoLens** can plot `subplots` which show multiple
+views of the dataset at once.
+
+The `aplt.subplot_imaging_dataset()` function plots the data, noise-map and PSF together.
+
+
+```python
+aplt.subplot_imaging_dataset(dataset=dataset)
+```
+
+
+
+![png](tutorial_0_visualization_files/tutorial_0_visualization_11_0.png)
+
+
+
+__Plot Customization__
+
+Does the figure display correctly on your computer screen?
+
+If not, the default matplotlib settings can be customized via the config files in:
+
+  autolens_workspace/config/visualize/
+
+Key config entries:
+
+ - `mat_wrap.yaml` -> Figure -> figure: -> figsize
+ - `mat_wrap.yaml` -> YLabel -> figure: -> fontsize
+ - `mat_wrap.yaml` -> XLabel -> figure: -> fontsize
+ - `mat_wrap.yaml` -> TickParams -> figure: -> labelsize
+ - `mat_wrap.yaml` -> YTicks -> figure: -> labelsize
+ - `mat_wrap.yaml` -> XTicks -> figure: -> labelsize
+
+For quick one-off adjustments you can pass `title=`, `colormap=`, and `use_log10=` directly:
+
+
+```python
+aplt.plot_array(array=dataset.data, title="Dataset Image (Log10)", use_log10=True)
+```
+
+
+
+![png](tutorial_0_visualization_files/tutorial_0_visualization_13_0.png)
+
+
+
+__Overlays__
+
+Overlays such as critical curves and image positions are added using the `lines=` and `positions=`
+keyword arguments.
+
+For example, we can compute the critical curves of a tracer and overlay them on the image.
+
+
+```python
+grid = al.Grid2D.uniform(shape_native=(100, 100), pixel_scales=0.05)
+
+lens_galaxy = al.Galaxy(
+    redshift=0.5,
+    mass=al.mp.Isothermal(centre=(0.0, 0.0), einstein_radius=1.6, ell_comps=(0.0, 0.0)),
+)
+
+source_galaxy = al.Galaxy(
+    redshift=1.0,
+    bulge=al.lp.SersicCoreSph(
+        centre=(0.0, 0.0), intensity=1.0, effective_radius=0.5, sersic_index=2.0
+    ),
+)
+
+tracer = al.Tracer(galaxies=[lens_galaxy, source_galaxy])
+
+tangential_critical_curve_list = al.LensCalc.from_tracer(
+    tracer=tracer
+).tangential_critical_curve_list_from(grid=grid)
+
+aplt.plot_array(
+    array=tracer.image_2d_from(grid=grid),
+    title="Tracer Image with Critical Curves",
+    lines=tangential_critical_curve_list,
+)
+```
+
+
+
+![png](tutorial_0_visualization_files/tutorial_0_visualization_15_0.png)
+
+
+
+__Wrap Up__
+
+Throughout the lectures you'll see lots more visuals plotted on figures and subplots.
+
+The key plotting functions you'll use are:
+
+ - `aplt.plot_array(array, title, ...)` — plot any 2D array.
+ - `aplt.plot_grid(grid, title, ...)` — plot a 2D grid of coordinates.
+ - `aplt.subplot_imaging_dataset(dataset)` — multi-panel dataset overview.
+ - `aplt.subplot_tracer(tracer, grid)` — multi-panel tracer overview.
+ - `aplt.subplot_fit_imaging(fit)` — multi-panel fit overview.
+
+Great! Hopefully, visualization in **PyAutoLens** is displaying nicely for us to get on with the
+**HowToLens** lecture series.
+
+
+```python
+
+```