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

CITATIONS.md

@@ -0,0 +1,14 @@
+# Citations & References
+
+The bibtex entries for **PyAutoFit** and its affiliated software packages can be found
+[here](https://github.com/rhayes777/PyAutoFit/blob/main/files/citations.bib), with example text for citing **PyAutoFit**
+in [.tex format here](https://github.com/rhayes777/PyAutoFit/blob/main/files/citations.tex) and
+[.md format here](https://github.com/rhayes777/PyAutoFit/blob/main/files/citations.md). As shown in the examples, we
+would greatly appreciate it if you mention **PyAutoFit** by name and include a link to our GitHub page!
+
+**PyAutoFit** is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.03127) and its
+entry in the above .bib file is under the citation key `pyautofit`.
+
+You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, Nautilus, 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.

README.md

@@ -0,0 +1,94 @@
+# HowToFit
+
+[Installation Guide](https://pyautofit.readthedocs.io/en/latest/installation/overview.html) |
+[PyAutoFit readthedocs](https://pyautofit.readthedocs.io/en/latest/index.html) |
+[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace)
+
+<img src="https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautofit.gif?raw=true" width="900" />
+
+Welcome to **HowToFit** — the tutorial lecture series for [PyAutoFit](https://github.com/PyAutoLabs/PyAutoFit),
+an open-source probabilistic programming library for Bayesian model fitting.
+
+**HowToFit** teaches new users how to compose, fit, and interpret probabilistic models with **PyAutoFit**.
+It assumes minimal prior knowledge of statistics and takes you from first principles — what a model is,
+what a non-linear search does, how a likelihood function is built — through to graphical and hierarchical
+models for fitting large datasets simultaneously.
+
+For experienced scientists who already know the fundamentals of Bayesian modeling, the
+[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) examples will be more appropriate —
+they are concise, API-focused, and assume the concepts taught in **HowToFit** as background.
+
+## Chapters
+
+- `chapter_1_introduction` — Models, likelihoods, non-linear searches, why modeling is hard, and how to
+  interpret the results of a fit.
+- `chapter_2_scientific_workflow` — Reserved for future material on building a full scientific
+  model-fitting workflow. Currently a stub; the corresponding overview lives in
+  `autofit_workspace/scripts/overview/overview_2_science_workflow.py`.
+- `chapter_3_graphical_models` — Fitting many datasets simultaneously with graphical models,
+  hierarchical models, and Expectation Propagation.
+
+Each chapter is organised into numbered tutorial files: `chapter_<N>_<name>/tutorial_<M>_<topic>.py`
+(Python script) or the matching `.ipynb` in `notebooks/`. Tutorials build on each other within a
+chapter and assume you have completed the earlier ones.
+
+## Getting Started
+
+You can run the tutorials on your own machine by following the
+[PyAutoFit installation guide](https://pyautofit.readthedocs.io/en/latest/installation/overview.html),
+then cloning this repository:
+
+```bash
+git clone https://github.com/PyAutoLabs/HowToFit.git
+cd HowToFit
+```
+
+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 — figures render inline, and you can step through small code blocks
+interactively. Use the Python scripts for actual **PyAutoFit** use.
+
+## Before Chapter 1
+
+Before starting chapter 1, open `start_here.py` for a one-page overview of the series, then begin
+`scripts/chapter_1_introduction/tutorial_1_models.py`.
+
+## Repository Structure
+
+- `scripts/` — Runnable Python tutorial scripts, one subfolder per chapter.
+- `notebooks/` — Jupyter notebook versions of the scripts (auto-generated; see below).
+- `config/` — **PyAutoFit** configuration YAML files used by the tutorials.
+- `dataset/` — Tutorial 1D datasets are generated at runtime by `scripts/simulators/simulators.py` —
+  no data 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 autofit_workspace
+
+[autofit_workspace](https://github.com/PyAutoLabs/autofit_workspace) is the main user-facing workspace
+for **PyAutoFit** — concise examples, cookbooks, and search templates aimed at users who already understand
+probabilistic modeling. **HowToFit** is the teaching companion. Tutorials in chapters 1 and 3 reference
+`autofit_workspace` scripts as the next place to go after the relevant concept has been introduced.
+
+## Citations
+
+If you use **HowToFit** or **PyAutoFit** in your research, please cite the references listed in
+`CITATIONS.rst`.
+
+## Community & Support
+
+Support for **PyAutoFit** 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
+[PyAutoFit GitHub issues page](https://github.com/PyAutoLabs/PyAutoFit/issues) (for library issues)
+or the [HowToFit GitHub issues page](https://github.com/PyAutoLabs/HowToFit/issues) (for tutorial
+content issues).

config/README.md

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

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
+Gaussian:
+  centre:
+    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.

config/visualize/README.md

@@ -0,0 +1,6 @@
+The `config` folder contains configuration files which customize default **PyAutoLens**.
+
+# Files
+
+- `general.yaml`: Customizes general visualization settings (e.g. the matplotlib backend).
+- `plots_search.yaml`: Customize which non-linear search figures are output during a model-fit.