Adding documentation from the airplane trip

CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: If you use this software, please cite it using these metadata.
+title: 'URSSI 2025 Summer School Documentation'
+date-released: 2025-08-03
+identifiers:
+- type: doi
+  value: 
+authors:
+- given-names: Timothy
+  family-names: Monko
+  affiliation: University of Minnesota — Twin Cities
+  orcid: https://orcid.org/0000-0003-4905-757X
+  alias: TimMonko
+repository-code: https://github.com/timmonko/urssi-docs
+license: BSD-3-Clause

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to [Tim Monko](https://github.com/TimMonko).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

LICENSE

@@ -0,0 +1,28 @@
+
+Copyright (c) 2025, Tim Monko
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/docstrings.md

@@ -0,0 +1,103 @@
+# 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.
+
+Most code documentation is *for developers*, but docstrings in particular are *for users*.
+
+However, my biggest caution is that code documentation can often be ignored and frequently goes out of date. Try to be mindful of this and also don't fully rely on docstrings to be fully correct. Yet, if you find something amiss in a docstrings, projects usually warmly welcome even "small" (i.e. typo) contributions to fix docstrings!
+
+Documenting code has many perspectives, here are a few perspectives that I have appreciated over time.
+
+!!! 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.
+
+Object names should bias towards descriptive rather than short. Single variables names are notoriously hard to understand (except in some cases like norms in list comprehension). Use "active" naming or verbs for functions / methods.
+
+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)
+
+## 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 
+
+```
+
+## 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. 
+
+`# 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.
+
+```python
+def threshold_otsu_minimum(img, min_value = None):
+    """Get threshold value of an image
+
+    Return the threshold value of an image. If the value determined by
+    Otsu's algorithm is smaller than a minimum_value, then return the minimum value. 
+    This strategy prevents thresholding below a specified value,
+    which is useful when an image may be all background and have no signal to threshold.
+    """
+    threshold = filters.threshold_otsu(img)
+    if min_value is not None and min_value > threshold:
+        threshold = min_value
+    return threshold
+
+
+def threshold_otsu_minimum(
+    img: np.ndarray,
+    min_value: int | float | None = None
+) -> int | float:
+    """Get Otsu's threshold or a minimum of an image
+
+    Parameters
+    ----------
+    img : np.ndarray
+        Image-like array to threshold
+    min_value : Optional
+        Minimum return value for the threshold
+
+    Returns
+    -------
+    threshold : int | float
+        Threshold value
+    """
+    ... 
+```
+
+## Tests?!?!
+
+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.
+
+## 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.
+2. Use `_object_name` to imply that the object is private and should not be relied on by users. This also can have a lower expectation for documentation, BUT tricky or frequently used private objects should still be documented :)

docs/index.md

@@ -1,6 +1,6 @@
-# Welcome to MkDocs
+# Documentation Guide for URSSI Summer School
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+This documentation is built using [MkDocs](https://www.mkdocs.org/) and is hosted on GitHub Pages.
 
 ## Commands
 
@@ -15,3 +15,8 @@ For full documentation visit [mkdocs.org](https://www.mkdocs.org).
     docs/
         index.md  # The documentation homepage.
         ...       # Other markdown pages, images and other files.
+
+## External Resources
+
+1. [Scientific Python documentation guide](https://learn.scientific-python.org/development/guides/docs/) - Focused on creating docs using Sphinx with Myst (markdown)
+2. [PyOpenSci documentation guide](https://www.pyopensci.org/python-package-guide/documentation/index.html) - Worth reading for a different perspective on writing documentation, with more focus on the why and how. Uses Sphinx, but this is not the core part of the documentaiton.

docs/repo_setup.md

@@ -0,0 +1,7 @@
+# Github Repo Documentation That Isn't a Website
+
+1. [README.md](https://www.pyopensci.org/python-package-guide/tutorials/add-readme.html) -- Also where CONTRIBUTING.md information can live
+2. [LICENSE](https://www.pyopensci.org/python-package-guide/tutorials/add-license-coc.html) -- use MIT or BSD3, generally
+3. [CODE_OF_CONDUCT.md](https://www.pyopensci.org/python-package-guide/tutorials/add-license-coc.html#what-is-a-code-of-conduct-file) -- use [Contributor Covenant](https://www.contributor-covenant.org/) with this [markdown text](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md)
+4. [CITATION.cff](https://citation-file-format.github.io/) -- recognized by Github, some Citation Managers, and [Zenodo](https://zenodo.org/) -- the latter of which is a great way to get a DOI for your repo!
+5. [Update pyproject.toml](https://www.pyopensci.org/python-package-guide/tutorials/pyproject-toml.html)

docs/versioning.md

@@ -0,0 +1,32 @@
+# Versioning
+
+To be forthright, I have no experience manually versioning code, so this tutorial will focus on using `git tags` for versioning. However, when I have seen others manually version code I often see mistakes and re-releases. It seems that using tagged versioning helps prevent some more typical mistakes. Furthermore, tagged versioning can also be a nice way to trigger CI for deployments.
+
+## 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! 
+
+## Versioning conventions (at least with Python)
+
+Version with 3 decimals. `0.0.0`
+
+In this order:
+`0.0.1a0` first alpha, often used to get out "working tags" for users to test specific changes, used especially if projects work from dev branches.
+`0.0.1b0` first beta. not as frequently used.
+`0.0.1rc0` first release candidate. the final build for testing.
+`0.0.1` full release
+
+## 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. 
+
+1. Checkout branch and/or commit intended for tagging. 
+2. `git tag ... `
+3. `git push`
+
+## 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 

mkdocs.yml

@@ -1,4 +1,20 @@
 site_name: 2025 URSSI Docs
 site_url: https://timmonko.github.io/urssi-docs/
 theme:
-  name: material
+  name: material
+
+markdown_extensions:
+  - admonition
+
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.tabbed:
+      alternate_style: true

pyproject.toml

@@ -1,9 +1,27 @@
 [project]
 name = "urssi-docs"
 version = "0.1.0"
-description = "Add your description here"
+description = "Documentation for the URSSI 2025 Summer School"
+authors = [
+  { name = "Tim Monko", email = "timmonko@gmail.com"},
+]
 readme = "README.md"
-requires-python = ">=3.13"
+license = {file = "LICENSE"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Documentation",
+]
+requires-python = ">=3.10"
 dependencies = [
     "mkdocs-material>=9.6.16",
 ]
+
+[project.urls] # Optional
+"Homepage" = "https://timmonko.github.io/urssi-docs/"
+"Bug Reports" = "https://github.com/timmonko/urssi-docs/issues"
+"Source" = "https://github.com/timmonko/urssi-docs/"