From bf38c6f3c2bc4a87e058287cc040b7a08af81edd Mon Sep 17 00:00:00 2001 From: alexo Date: Fri, 29 Dec 2023 22:11:12 +1100 Subject: [PATCH] docs: update docs --- README.md | 5 +++++ docs/autodoc.md | 19 ++++++++----------- docs/ci.md | 46 +++++++++++++++++++++++++++++++--------------- docs/index.rst | 6 +++--- docs/modules.rst | 2 +- 5 files changed, 48 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index c6cced6..ed993c6 100644 --- a/README.md +++ b/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 === diff --git a/docs/autodoc.md b/docs/autodoc.md index 1e71a4f..96794bd 100644 --- a/docs/autodoc.md +++ b/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` \ No newline at end of file diff --git a/docs/ci.md b/docs/ci.md index 1e71a4f..64f0267 100644 --- a/docs/ci.md +++ b/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` \ No newline at end of file +`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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 20b9db7..b0d627f 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/modules.rst b/docs/modules.rst index 873f480..540e1a3 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -2,7 +2,7 @@ adventofcode2023 ================ .. toctree:: - :maxdepth: 4 + :maxdepth: 1 day01 day02