docs: update docs

README.md

@@ -7,6 +7,11 @@ Advent of Code 2023
 
 Website: https://adventofcode.com/2023
 
+API documentation and more information:
+
+https://alex-ong.github.io/adventofcode2023/index.html
+
+
 Setup
 ===
 

docs/autodoc.md

@@ -1,24 +1,21 @@
-Automatic documentation
-===
+# Automatic documentation
+
 
 The documentation in this repo was setup using this guide:
 https://redandgreen.co.uk/sphinx-to-github-pages-via-github-actions/
 
 
-Key commands
-===
-
-Setup from scratch: 
+## Key commands
 
-`cd /docs`
-`sphinx-quickstart`
+* Setup from scratch: 
+`cd /docs && sphinx-quickstart`
 
-Generate .rst's automatically (from root directory)
+* Generate .rst's automatically (from root directory)
 `sphinx-apidoc -o docs .`
 
-Manually generate html (already done in Github Action):
+* Manually generate html (already done in Github Action):
 `cd docs && make html`
 
-Clean html
+* Clean html
 
 `cd docs && make clean`

docs/ci.md

@@ -1,24 +1,40 @@
-Automatic documentation
-===
+# Continuous Integration
 
-The documentation in this repo was setup using this guide:
-https://redandgreen.co.uk/sphinx-to-github-pages-via-github-actions/
+CI allows lots of processes to occur automatically
 
+Think of `pre-commit` as "local" and `github actions` as cloud.
 
-Key commands
-===
+1. `pre-commit` is a tool that runs arbitrary scripts at `pre-commit` and `pre-push` time. You can reuse it's config for github-action based scripts, to ensure all ci scripts are run.
 
-Setup from scratch: 
+2. `github actions` (see `.github/workflows`) are workflows that run "on the cloud" on github.com. They run based on a few conditions such as pushing/merging, PRs etc. They mainly just setup an linux box to install `pre-commit` and then duplicate what was being done on a local environment. They also publish our html documentation (such as this page) into the `gh-pages` branch.
 
-`cd /docs`
-`sphinx-quickstart`
 
-Generate .rst's automatically (from root directory)
-`sphinx-apidoc -o docs .`
+## Tools
 
-Manually generate html (already done in Github Action):
-`cd docs && make html`
 
-Clean html
+### Pre-commit
 
-`cd docs && make clean`
+`pre-commit` is both the name of a tool, and of a stage in committing.
+
+This section details what is done at the stages
+1. `pre-commit`: runs `ruff-linting` and `mypy` and `mixed-crlf`. These are all very fast and ensure commits have barebones checks before going in.
+
+2. `pre-push`: runs `pytest unit tests` as well as `coverage`
+
+### ruff
+A simple tool that does linting
+
+### mypy
+Type-checking tool
+
+### mixed-crlf
+Ensures that we don't commit any `crlf` files. Converts all to `lf`
+
+### pytest
+Unit testing framework
+
+### coverage
+`Coverage` is a simple tool that tells you what % of your code is covered by tests. This can be easily gamed, for example a test that is `assert main() == 0` will result in very high coverage but not necessarily good tests.
+
+### sphinx
+Generates `.rst` files and `html` files automatically. You can inject markdown manually. Check the [autodoc](autodoc.md) page for more information.

docs/index.rst

@@ -7,11 +7,11 @@ Welcome to adventofcode2023's documentation!
 ============================================
 
 .. toctree::
-   :maxdepth: 2
    :caption: Contents:
+   :maxdepth: 1
 
-   autodoc.md
-   ci.md
+   autodoc
+   ci
    modules
 
 

docs/modules.rst

@@ -2,7 +2,7 @@ adventofcode2023
 ================
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
 
    day01
    day02