Cleanup files for teaching

docs/advanced_markdown.md

@@ -31,7 +31,7 @@ def hello_world():
 
 ## Emojis :cat:
 
-Emojis can bcan be added with the mkdocs markdown extension `pymdownx.emoji`. To use it, add the following to your `mkdocs.yml`:
+Emojis can can be added with the mkdocs markdown extension `pymdownx.emoji`. To use it, add the following to your `mkdocs.yml`:
 
 ```yaml
 markdown_extensions:
@@ -87,4 +87,3 @@ $E = mc^2$
 `$$\int_0^\infty e^{-x} dx = 1$$` block form
 
 $$\int_0^\infty e^{-x} dx = 1$$
-

docs/docs_setup.md

@@ -1,25 +1,18 @@
-# Creating documentation with uv and MkDocs
+# Creating documentation with MkDocs
 
 For preparing documentation, we will use [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/). The Material theme is first class for MkDocs, and in fact many plugins are set up for Material and not the default MkDocs theme.
 
 ## Get MkDocs locally
 
-```bash
-uv init
-uv add mkdocs-material
-```
-
-or
+We want to create a `pyproject.toml` file if we don't have one already, and then add `mkdocs-material` as an **optional** dependency. This will allow us to use the Material theme and plugins that are compatible with it (which is more than just mkdocs).
 
-```bash
-uv pip install mkdocs-material
-```
+Then after activating the environment: `pip install -e ".[docs]"`
 
 ## Initialize a new MkDocs project
 
 ```bash
-uv run mkdocs new .
-uv run mkdocs serve
+mkdocs new .
+mkdocs serve
 ```
 
 Follow the [setup instructions](https://squidfunk.github.io/mkdocs-material/creating-your-site/) from mkdocs-material.
@@ -33,7 +26,7 @@ Make commits and push to your repo, preferably with a PR. (See [Recommended Gith
 To build the documentation locally, use
 
 ```bash
-uv run mkdocs build
+mkdocs build
 ```
 
 And it will create a `site/` directory with the built documentation.

docs/docstrings.md

@@ -1,6 +1,6 @@
 # Code Documentation
 
-In my experience docstrings and code style are the **best** way to assist reviewers of code -- both your future self and colleagues. Also, this is the documentation that saves yours and others life when it comes to future contribution. As such, this page will reflect on a variety of perhaps surprising ways that code gets documentated.
+In my experience docstrings and code style are the **best** way to assist reviewers of code -- both your future self and colleagues. Also, this is the documentation that saves yours and others life when it comes to future contribution. As such, this page will reflect on a variety of perhaps surprising ways that code gets documented.
 
 Most code documentation is *for developers*, but docstrings in particular are *for users*.
 
@@ -11,8 +11,6 @@ Documenting code has many perspectives, here are a few perspectives that I have
 !!! note
     Sections have an opinionated order from most to least important.
 
-## Suggested Reading
-
 ## Object Names
 
 This is where documentation starts and is why its deserving of its own section. If objects are named poorly it becomes a real challenge to follow code.
@@ -22,28 +20,25 @@ Object names should bias towards descriptive rather than short. Single variables
 Longer names can be an especially useful form of self documentation, especially when objects are re-used across a codebase. 
 
 1. `img_array_width` not `width`
-2. `calculate_max_of_array()` not `do_math()` (see ![Typing] though)
+2. `calculate_max_of_array()` not `do_math()` (see [Typing](docstrings.md#typing) though)
 
 ## Docstrings
 
 These are especially helpful for collaboration with developers *and* are the main way to communicate to users. IDEs can richly show information if both docstrings and the IDE is set up correctly. Docstrings can be extremely powerful ways to document API, and docs tooling makes it very easy to add this to your website.
 
-```python
-def 
-
-```
+Great reading from [PyOpenSci](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html)
 
 ## Commenting code
 
 Documentation of functionality via comments should be reserved for instances where the aforementioned code documentation is *insufficient* to understand what some lines are code are doing. Generally this explains as much *why* the implementation exists as it does *what* the implementation is.
 
-Other uses of comments include linking to references, such as external documentation, PRs, or explanations of bug/fixes. 
+Other uses of comments include linking to references, such as external documentation, PRs, or explanations of bug/fixes.
 
 `# TODO` can be used if you need to bookmark anything and is universal enough to be highlighted in some IDEs.
 
 ## Typing
 
-I am not here to endorse Typing as the "correct" way to write Python (indeed, I'm hesistant with some perspectives towards typing). BUT, I am here to show you how (minimally) typing your code greatly helps. Typing can also show up in IDEs, which helps users and developers work with your code.
+I am not here to endorse Typing as the "correct" way to write Python (indeed, I'm hesitant with some perspectives towards typing). BUT, I am here to show you how (minimally) typing your code greatly helps. Typing can also show up in IDEs, which helps users and developers work with your code.
 
 ```python
 def threshold_otsu_minimum(img, min_value = None):
@@ -70,12 +65,12 @@ def threshold_otsu_minimum(
     ----------
     img : np.ndarray
         Image-like array to threshold
-    min_value : Optional
+    min_value : int or float or None, optional
         Minimum return value for the threshold
 
     Returns
     -------
-    threshold : int | float
+    threshold : int or float
         Threshold value
     """
     ... 
@@ -85,18 +80,15 @@ def threshold_otsu_minimum(
 
 Tests are another form of documentation. Tests help us crystallize for both ourselves and for collaborators the purpose of our code. At least for unit tests, they can also form a sort of documentation. Just some encouragement to take the time to write tests, they are as important as making functions that (you think) work.
 
-```python
-def test_threshold_otsu_with_minimum():
-
-
-```
-
 ## Code Style
 
 Following a consistent code style can greatly help readability and understanding of a codebase. Sometimes, code style can become a mess in projects, and it also becomes harder to contribute to that project because there is uncertainty on even how to start writing code. If a project has a fairly regular codestyle, don't be afraid to contribute because these projects are (usually) very helpful at providing suggestions to adopt code to meet any standards that might exist. This particularly is better is the enemy of the good.
 
 [PyOpenSci](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html#three-python-docstring-formats-and-why-we-like-numpy-style) has better words than I can write.
 
+You can also enforce code style or "lint" code with tools like ruff and pre-commit hooks.
+[ruff](https://github.com/astral-sh/ruff) is the quickest way to get started, but really its a combination of so many previously used linting tools like Black, isort, flake8...
+
 ## Other Tips
 
 1. Functions / Methods should be visible on "one screen", so about 25 lines. Makes much easier to review! And you'll thank yourself! This generally helps with that "do one thing" that people who clearly understand things that way will say.

docs/versioning.md

@@ -4,9 +4,9 @@ To be forthright, I have no experience manually versioning code, so this tutoria
 
 ## Versioning frameworks
 
-1. EffVer (Effective): Effective versioning. How much effort does it take to upgrade to the new version? `super.major.minor` Where minor introduces little to no breaking changes, but can introduce features. Major is usually a shift in dependencies, API changes, and dropping old versions of things like Python. Super are the big API re-rewrites or foundational milestones.
-2. SemVer (Semantic): Semantic versioning. `major.minor.bugfix`. Supposedly, projects out of beta should be at 1.0.0+ but this rarely happens. 
-3. CalVer (Calendar): Use the date of release for the version. Version is self explanatory, but the type of release is certinaly not! 
+1. [EffVer (Effective)](https://jacobtomlinson.dev/effver/): Effective versioning. How much effort does it take to upgrade to the new version? `super.major.minor` Where minor introduces little to no breaking changes, but can introduce features. Major is usually a shift in dependencies, API changes, and dropping old versions of things like Python. Super are the big API re-rewrites or foundational milestones.
+2. SemVer (Semantic): Semantic versioning. `major.minor.bugfix`. Supposedly, projects out of beta should be at 1.0.0+ but this rarely happens.
+3. CalVer (Calendar): Use the date of release for the version. Version is self explanatory, but the type of release is certainly not!
 
 ## Versioning conventions (at least with Python)
 
@@ -20,13 +20,18 @@ In this order:
 
 ## Tagging with `git`
 
-First, we'll use a `git` workflow to add tags with the understanding that this is what a repo host like GitHub is doing when a tag is created on the webpage. 
+First, we'll use a `git` workflow to add tags with the understanding that this is what a repo host like GitHub is doing when a tag is created on the webpage.
 
-1. Checkout branch and/or commit intended for tagging. 
-2. `git tag ... `
-3. `git push`
+1. Checkout branch and/or commit intended for tagging.
+2. `git tag "v0.1.3rc2"` is sufficient
+3. `git tag -s "v0.1.3rc2" -F release_0_1_3.md` sign and add a message to the tag. The `-F` flag will read the file and use it as the message. You can also use `-m` to add a message directly in the command line.
+4. `git push <remote> --tags` will push the tags to the remote.
 
 ## Tagging with GitHub
 
-1. Click the tag-looking button or go to releases and "draft a new release"
-2. Auto-generate release notes; the commits between last full-release and this release will 
+Much more beginner friendly, you should be doing this at the very minimum!
+
+1. Click the tag-looking button or go to releases and "Create a new release"
+2. Select a tag or create a new one (usually the latter) - prefix with `v` for version.
+3. "Generate release notes"; the commits between last full-release and this release will autopopulate the description.
+4. On Publish release, the tag will be created and pushed to the repo, if any actions are set up they will run, like deploying docs or a package to PyPI.