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

CITATIONS.md

@@ -0,0 +1,16 @@
+# Citations & References
+
+The bibtex entries for **PyAutoGalaxy** and its affiliated software packages can be found
+[here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.bib), with example text for citing **PyAutoGalaxy**
+in [.tex format here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.tex) format here and
+[.md format here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.md).
+
+As shown in the examples, we would greatly appreciate it if you mention **PyAutoGalaxy** by name and include a link to
+our GitHub page!
+
+**PyAutoGalaxy** 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 `pyautogalaxy`.
+
+You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, PySwarms, 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,98 @@
+# HowToGalaxy
+
+[Installation Guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html) |
+[PyAutoGalaxy readthedocs](https://pyautogalaxy.readthedocs.io/en/latest/index.html) |
+[autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace)
+
+<img src="https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautogalaxy.gif?raw=true" width="900" />
+
+Welcome to **HowToGalaxy** — the tutorial lecture series for [PyAutoGalaxy](https://github.com/PyAutoLabs/PyAutoGalaxy),
+an open-source library for modeling the light of galaxies.
+
+**HowToGalaxy** teaches new users how to model galaxy morphologies from scratch. It assumes minimal prior
+knowledge of astronomy or statistics and takes you from first principles all the way to using
+**PyAutoGalaxy** for professional scientific research.
+
+For experienced scientists who already know the fundamentals of galaxy light profile fitting and Bayesian
+modeling, the [autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) examples will be
+more appropriate — they are concise and assume the concepts taught in **HowToGalaxy** as background.
+
+## Chapters
+
+- `chapter_1_introduction` — An introduction to galaxy morphology and **PyAutoGalaxy**: grids, light
+  profiles, galaxies, simulated imaging data, and fitting.
+- `chapter_2_modeling` — Bayesian inference, non-linear searches, and how to fit a galaxy model to CCD
+  imaging data with **PyAutoGalaxy**.
+- `chapter_3_search_chaining` — Chaining multiple non-linear searches together to build automated galaxy
+  modeling pipelines for complex systems.
+- `chapter_4_pixelizations` — Pixelized source reconstructions (inversions) for galaxies with irregular
+  morphologies.
+- `chapter_optional` — Optional tutorials on alternative non-linear searches and other advanced topics.
+
+**HowToGalaxy** 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 galaxy modeling in the
+`autogalaxy_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
+[PyAutoGalaxy installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html),
+then cloning this repository:
+
+```bash
+git clone https://github.com/PyAutoLabs/HowToGalaxy.git
+cd HowToGalaxy
+```
+
+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 **PyAutoGalaxy** 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 **PyAutoGalaxy** installation, walks you through how
+images and figures display in Jupyter, and configures matplotlib for the rest of the tutorial series.
+
+## Repository Structure
+
+- `scripts/` — Runnable Python tutorial scripts, one subfolder per chapter.
+- `notebooks/` — Jupyter notebook versions of the scripts (auto-generated; see below).
+- `config/` — **PyAutoGalaxy** configuration YAML files used by the tutorials.
+- `dataset/` — Tutorial datasets are generated at runtime by scripts in `scripts/simulators/` —
+  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 autogalaxy_workspace
+
+[autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) is the main user-facing
+workspace for **PyAutoGalaxy** — concise examples, guides, and science templates aimed at users who have
+a working understanding of galaxy morphology and light profile fitting. **HowToGalaxy** is the teaching
+companion. Many tutorials in chapters 2–4 reference `autogalaxy_workspace` scripts as the next place to
+go after the relevant concept has been introduced.
+
+## Citations
+
+If you use **HowToGalaxy** or **PyAutoGalaxy** in your research, please cite the references listed in
+`CITATIONS.rst`.
+
+## Community & Support
+
+Support for **PyAutoGalaxy** 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
+[PyAutoGalaxy GitHub issues page](https://github.com/PyAutoLabs/PyAutoGalaxy/issues) (for library issues)
+or the [HowToGalaxy GitHub issues page](https://github.com/PyAutoLabs/HowToGalaxy/issues) (for tutorial
+content issues).

config/README.md

@@ -0,0 +1,14 @@
+The `config` folder contains configuration files which customize default **PyAutoGalaxy**.
+
+# 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
+
+- `generag.yaml`: Customizes general **PyAutoGalaxy** settings.
+- `logging.yaml`: Customizes the logging behaviour of **PyAutoGalaxy**.

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
+**PyAutoGalaxy**.
+
+# 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 'autogalaxy_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/priors/ellipse/README.rst → config/priors/ellipse/README.md

@@ -1,6 +1,6 @@
-The ``ellipse`` folder contains configuration files for the default priors assumed for ``ellipse`` objects.
-
-These model components are used for ellipse isophote fitting, which models the surface brightness of a galaxy as a
-series of ellipses, which can include multipole perturbations.
-
-The main object used for modeling is the `Ellipse` object, with a list of `Ellipse` objects used to model the galaxy.
+The `ellipse` folder contains configuration files for the default priors assumed for `ellipse` objects.
+
+These model components are used for ellipse isophote fitting, which models the surface brightness of a galaxy as a
+series of ellipses, which can include multipole perturbations.
+
+The main object used for modeling is the `Ellipse` object, with a list of `Ellipse` objects used to model the galaxy.