docs: convert prose .rst to MyST .md (pass 2)

CITATIONS.md

@@ -0,0 +1,26 @@
+# Citations & References
+
+The bibtex entries for **PyAutoLens** and its affiliated software packages can be found
+[here](https://github.com/Jammy2211/PyAutoLens/blob/main/files/citations.bib), with example text for citing **PyAutoLens**
+in [.tex format here](https://github.com/Jammy2211/PyAutoLens/blob/main/files/citations.tex) format here and
+[.md format here](https://github.com/Jammy2211/PyAutoLens/blob/main/files/citations.md). As shown in the examples, we
+would greatly appreciate it if you mention **PyAutoLens** by name and include a link to our GitHub page!
+
+**PyAutoLens** is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.02825#) and its
+entry in the above .bib file is under the citation key `pyautolens`. Please also cite the MNRAS AutoLens
+papers (<https://academic.oup.com/mnras/article/452/3/2940/1749640> and <https://academic.oup.com/mnras/article-abstract/478/4/4738/5001434?redirectedFrom=fulltext>) which are included
+under the citation keys `Nightingale2015` and `Nightingale2018`.
+
+You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, etc) in
+the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes
+the citation key for all of these projects.
+
+If you use decomposed mass models (e.g. stellar mass models like an `Sersic` or dark matter models like
+an `NFW`) please cite the following paper <https://arxiv.org/abs/2106.11464> under
+citation key `Oguri2021`. Our deflection angle calculations are based on this method.
+
+If you specifically use a decomposed mass model with the `gNFW` please cite the following paper <https://academic.oup.com/mnras/article/488/1/1387/5526256> under
+citation key `Anowar2019`.
+
+The citations.bib file above also includes my work on [using strong lensing to study galaxy structure](https://ui.adsabs.harvard.edu/abs/2019MNRAS.489.2049N/abstract). If you're feeling kind, please go ahead and stick
+a citation in your introduction using citep\{Nightingale2019} or [@Nightingale2019] ;).

README.md

@@ -0,0 +1,105 @@
+# HowToLens
+
+[Installation Guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html) |
+[PyAutoLens readthedocs](https://pyautolens.readthedocs.io/en/latest/index.html) |
+[autolens_workspace](https://github.com/PyAutoLabs/autolens_workspace)
+
+<img src="https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautolens.gif?raw=true" width="900" />
+
+Welcome to **HowToLens** — the tutorial lecture series for [PyAutoLens](https://github.com/PyAutoLabs/PyAutoLens),
+an open-source library for strong gravitational lens modeling.
+
+**HowToLens** teaches new users what strong gravitational lensing is and how to model it from scratch. It assumes
+minimal prior knowledge of astronomy or statistics and takes you from first principles all the way to using
+**PyAutoLens** for professional scientific research.
+
+For experienced scientists who already know the fundamentals of strong lensing and Bayesian modeling, the
+[autolens_workspace](https://github.com/PyAutoLabs/autolens_workspace) examples will be more appropriate —
+they are concise and assume the concepts taught in **HowToLens** as background.
+
+## Chapters
+
+- `chapter_1_introduction` — An introduction to strong gravitational lensing and **PyAutoLens**: grids, light
+  and mass profiles, galaxies, ray-tracing, simulated imaging data, and fitting.
+- `chapter_2_lens_modeling` — Bayesian inference, non-linear searches, and how to fit a lens model to CCD
+  imaging data with **PyAutoLens**.
+- `chapter_3_search_chaining` — Chaining multiple non-linear searches together to build automated lens
+  modeling pipelines for complex systems.
+- `chapter_4_pixelizations` — Pixelized source reconstructions (inversions) for sources with irregular
+  morphologies.
+- `chapter_optional` — Optional tutorials on alternative non-linear searches and other advanced topics.
+
+**HowToLens** currently sits at four chapters. Each chapter will take around a day to work through.
+We recommend completing chapters 1 and 2, then applying what you've learned to real lens modeling in the
+`autolens_workspace` before returning for the more advanced material in chapters 3 and 4.
+
+## Getting Started
+
+You can run the tutorials on your own machine by following the
+[PyAutoLens installation guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html),
+then cloning this repository:
+
+```bash
+git clone https://github.com/PyAutoLabs/HowToLens.git
+cd HowToLens
+```
+
+Alternatively, every tutorial can be opened directly in Google Colab via the links in each chapter's
+`README.md`.
+
+The tutorials are distributed as both Jupyter notebooks (`notebooks/`) and Python scripts (`scripts/`).
+We recommend the notebooks for reading — images and plots render inline, and you can step through small
+code blocks interactively. Use the Python scripts for actual **PyAutoLens** use, which is the workflow
+chapter 3 onwards transitions you to.
+
+## Before Chapter 1
+
+Before starting chapter 1, complete `scripts/chapter_1_introduction/tutorial_0_visualization.py`
+(or the equivalent notebook). This confirms your **PyAutoLens** installation, walks you through how images
+and figures display in Jupyter, and configures matplotlib for the rest of the tutorial series.
+
+## Lensing Theory
+
+**HowToLens** assumes minimal previous knowledge of gravitational lensing. It is helpful to have the following
+lecture course on gravitational lensing by Massimo Meneghetti open as you go through the tutorials:
+
+<http://www.ita.uni-heidelberg.de/~massimo/sub/Lectures/gl_all.pdf>
+
+## Repository Structure
+
+- `scripts/` — Runnable Python tutorial scripts, one subfolder per chapter.
+- `notebooks/` — Jupyter notebook versions of the scripts (auto-generated; see below).
+- `config/` — **PyAutoLens** configuration YAML files used by the tutorials.
+- `dataset/` — Tutorial datasets are generated at runtime by scripts in `scripts/simulator/` —
+  no `.fits` files are committed.
+- `output/` — Model-fit results (generated at runtime, not committed).
+
+## Notebooks vs Scripts
+
+Notebooks in `notebooks/` are generated from the Python files in `scripts/`. **Always edit the \`\`.py\`\`
+scripts, never the notebooks directly.** The `# %%` markers in each script alternate between code and
+markdown cells, which [PyAutoBuild](https://github.com/PyAutoLabs/PyAutoBuild) uses to produce the
+`.ipynb` files.
+
+## Relationship to autolens_workspace
+
+[autolens_workspace](https://github.com/PyAutoLabs/autolens_workspace) is the main user-facing workspace
+for **PyAutoLens** — concise examples, guides, and science templates aimed at users who have a working
+understanding of strong lensing. **HowToLens** is the teaching companion. Many tutorials in chapters 2–4
+reference `autolens_workspace` scripts as the next place to go after the relevant concept has been
+introduced.
+
+## Citations
+
+If you use **HowToLens** or **PyAutoLens** in your research, please cite the references listed in
+`CITATIONS.rst`.
+
+## Community & Support
+
+Support for **PyAutoLens** is available via our Slack workspace. Slack is invitation-only; send an email
+if you'd like an invite.
+
+For installation issues, bug reports, or feature requests, raise an issue on the
+[PyAutoLens GitHub issues page](https://github.com/PyAutoLabs/PyAutoLens/issues) (for library issues)
+or the [HowToLens GitHub issues page](https://github.com/PyAutoLabs/HowToLens/issues) (for tutorial
+content issues).

config/README.md

@@ -0,0 +1,14 @@
+The `config` folder contains configuration files which customize default **PyAutoLens**.
+
+# Folders
+
+- `grids`: Configs for default behaviour of grids when used for ray-tracing.
+- `non-linear`: Configs for default non-linear search (e.g. MCMC, nested sampling) settings.
+- `notation`: Configs defining labels and formatting of model parameters when used for visualization.
+- `priors`: Configs defining default priors assumed on every model component and set of parameters.
+- `visualize`: Configs defining what images are output by a model fit.
+
+# Files
+
+- `general.yaml`: Customizes general **PyAutoLens** settings.
+- `logging.yaml`: Customizes the logging behaviour of **PyAutoLens**.

config/non_linear/README.md

@@ -0,0 +1,8 @@
+The `non_linear` folder contains configuration files which customize the default behaviour of non-linear searches in
+**PyAutoLens**.
+
+# Files
+
+- `mcmc.yaml`: Settings default behaviour of MCMC non-linear searches (e.g. Emcee).
+- `nest.yaml`: Settings default behaviour of nested sampler non-linear searches (e.g. Dynesty).
+- `mle.yaml`: Settings default behaviour of maximum likelihood estimator (mle) searches (e.g. LBFGS).

config/priors/README.md

@@ -0,0 +1,42 @@
+The prior config files contain the default priors and related variables for every light profile and mass profile
+when it is used as a model.
+
+They appear as follows:
+
+```bash
+Sersic:
+  effective_radius:
+    type: Uniform
+    lower_limit: 0.0
+    upper_limit: 100.0
+    width_modifier:
+      type: Absolute
+      value: 20.0
+    limits:
+      lower: -inf
+      upper: inf
+```
+
+The sections of this example config set the following:
+
+> type {Uniform, Gaussian, LogUniform}
+>
+> : The default prior given to this parameter when used by the non-linear search. In the example above, a
+>   UniformPrior is used with lower_limit of 0.0 and upper_limit of 4.0. A GaussianPrior could be used by
+>   putting "Gaussian" in the "type" box, with "mean" and "sigma" used to set the default values. Any prior can be
+>   set in an analogous fashion (see the example configs).
+>
+> width_modifier
+>
+> : When the results of a search are passed to a subsequent search to set up the priors of its non-linear search,
+>   this entry describes how the Prior is passed. For a full description of prior passing, checkout the examples
+>   in 'autolens_workspace/examples/complex/linking'.
+>
+> limits
+>
+> : When the results of a search are passed to a subsequent search, they are passed using a GaussianPrior. The
+>   limits set the physical lower and upper limits of this GaussianPrior, such that parameter samples
+>   can not go beyond these limits.
+
+The files `template_module.yaml` and `TemplateObject.yaml` give templates one can use to set up prior default
+configs for your own model components.