From 30bfbb10936203b609ecf5772632d16260a65c40 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 3 Aug 2025 20:02:38 -0500 Subject: [PATCH 01/11] add repo docs info --- docs/repo_setup.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/repo_setup.md b/docs/repo_setup.md index d54ea65..55c4a35 100644 --- a/docs/repo_setup.md +++ b/docs/repo_setup.md @@ -3,5 +3,9 @@ 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) +<<<<<<< HEAD 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) \ No newline at end of file +5. [Update pyproject.toml](https://www.pyopensci.org/python-package-guide/tutorials/pyproject-toml.html) +======= +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! +>>>>>>> 11df46d (add repo docs info) From ea4eeb2dfc72373227d89dcb2283b1f8237fafd0 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 3 Aug 2025 20:07:31 -0500 Subject: [PATCH 02/11] add citation --- docs/repo_setup.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/repo_setup.md b/docs/repo_setup.md index 55c4a35..c2fe3d3 100644 --- a/docs/repo_setup.md +++ b/docs/repo_setup.md @@ -3,9 +3,5 @@ 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) -<<<<<<< HEAD 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) -======= -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! ->>>>>>> 11df46d (add repo docs info) From 711f1d2572acc78b8f25556d49b9987f67173029 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 19:11:05 -0500 Subject: [PATCH 03/11] taking kid to potty --- docs/docstrings.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docstrings.md diff --git a/docs/docstrings.md b/docs/docstrings.md new file mode 100644 index 0000000..e69de29 From f3b00d128f9d4788f2f524337a22e196b954face Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 19:11:16 -0500 Subject: [PATCH 04/11] taking kid to potty --- docs/docstrings.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/docstrings.md b/docs/docstrings.md index e69de29..2ac8bcd 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -0,0 +1,25 @@ +# Docstrings + +Documenting code has many perspectives, here are a few perspectives that I have appreciated over time. + +Key Points (somewhat ordered from most to least important): + +## Object Names + +## Function / Method + +1. Function / Class / Variable names should have descriptive names. + 1. Single variable names are notoriously hard to understand bad + 2. Use actions for functions / methods + 3. Longer names can be useful as a form of self documentation, especially when objects are re-used across modules. + 1. `width` is much less clear than `img_array_width` +2. Docstrings should be used to the + +## Commenting code + +Documentation via comments should be reserved for instances where the aforementioned code documentation is *insufficient* to understand what some lines are code are doing. Usually, + +```python +def + +``` \ No newline at end of file From 5edd65ed9257c429298570cd786f2c845a219158 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 19:37:59 -0500 Subject: [PATCH 05/11] taking kid to potty again --- docs/docstrings.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/docstrings.md b/docs/docstrings.md index 2ac8bcd..7f205f1 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -1,4 +1,8 @@ -# Docstrings +# Documentation of Code + +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*. Documenting code has many perspectives, here are a few perspectives that I have appreciated over time. @@ -6,7 +10,7 @@ Key Points (somewhat ordered from most to least important): ## Object Names -## Function / Method + 1. Function / Class / Variable names should have descriptive names. 1. Single variable names are notoriously hard to understand bad @@ -15,6 +19,8 @@ Key Points (somewhat ordered from most to least important): 1. `width` is much less clear than `img_array_width` 2. Docstrings should be used to the +## Docstrings + ## Commenting code Documentation via comments should be reserved for instances where the aforementioned code documentation is *insufficient* to understand what some lines are code are doing. Usually, @@ -22,4 +28,14 @@ Documentation via comments should be reserved for instances where the aforementi ```python def -``` \ No newline at end of file +``` + +## Code Style + +## Tests?!?! + +Tests are another form of documentation. Tests help us crystallize what we + +## 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. \ No newline at end of file From 2f977f36d34d56573b9b6226f6a79163340a591d Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 20:26:24 -0500 Subject: [PATCH 06/11] taking kid to potty again ?!?!?!?! --- docs/docstrings.md | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/docstrings.md b/docs/docstrings.md index 7f205f1..19f2d34 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -1,37 +1,53 @@ # Documentation of Code -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 documentated. Most code documentation is *for developers*, but docstrings in particular are *for users*. Documenting code has many perspectives, here are a few perspectives that I have appreciated over time. -Key Points (somewhat ordered from most to least important): +```{tip} +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. -1. Function / Class / Variable names should have descriptive names. - 1. Single variable names are notoriously hard to understand bad - 2. Use actions for functions / methods - 3. Longer names can be useful as a form of self documentation, especially when objects are re-used across modules. - 1. `width` is much less clear than `img_array_width` -2. Docstrings should be used to the +Longer names can be an especially useful form of self documentation, especially when objects are re-used across a codebase. -## Docstrings +1. `img_array_width` not `width` +2. `calculate_max_of_array()` not `do_math()` (see ![Typing] though) -## Commenting code +## Docstrings -Documentation via comments should be reserved for instances where the aforementioned code documentation is *insufficient* to understand what some lines are code are doing. Usually, +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 ```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 + +## Typing + +I'm not + ## Code Style +Following a consistent code style can greatly help readability and understanding + ## Tests?!?! Tests are another form of documentation. Tests help us crystallize what we From 6390e33cc5eb639f90f09cfc76293b3fcacf46b0 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 21:45:40 -0500 Subject: [PATCH 07/11] ok now shes trying to sleep --- docs/docstrings.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/docstrings.md b/docs/docstrings.md index 19f2d34..7362d65 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -42,7 +42,42 @@ Other uses of comments include linking to references, such as external documenta ## Typing -I'm not +I'm not here to endorse Typing as the "correct" way to write Python. 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 + ... +``` ## Code Style From 7dfb21c15419e3bb75f4752d2f8e33992a469bc9 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 21:55:34 -0500 Subject: [PATCH 08/11] hiting quite the turbulence --- docs/docstrings.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docstrings.md b/docs/docstrings.md index 7362d65..2f4904e 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -1,4 +1,4 @@ -# Documentation of Code +# 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. @@ -42,7 +42,7 @@ Other uses of comments include linking to references, such as external documenta ## Typing -I'm not here to endorse Typing as the "correct" way to write Python. 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 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): @@ -79,13 +79,13 @@ def threshold_otsu_minimum( ... ``` -## Code Style +## Tests?!?! -Following a consistent code style can greatly help readability and understanding +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. -## Tests?!?! +## Code Style -Tests are another form of documentation. Tests help us crystallize what we +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. ## Other Tips From d54320b647217bc51c77246bc4bfbdaeaa9e0c2a Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 22:49:12 -0500 Subject: [PATCH 09/11] nearing end of code docs --- docs/docstrings.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/docstrings.md b/docs/docstrings.md index 2f4904e..2d4eda7 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -4,6 +4,8 @@ In my experience docstrings and code style are the **best** way to assist review 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. ```{tip} @@ -13,7 +15,6 @@ 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. @@ -27,7 +28,7 @@ Longer names can be an especially useful form of self documentation, especially ## 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 +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 @@ -38,7 +39,9 @@ def 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 +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 @@ -83,10 +86,17 @@ 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. ## 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. \ No newline at end of file +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 :) From 2ebb95febc139fe03f1d13667f57910234d361ae Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Sun, 10 Aug 2025 23:09:06 -0500 Subject: [PATCH 10/11] add versioning info --- docs/versioning.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/versioning.md diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 0000000..b968586 --- /dev/null +++ b/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 \ No newline at end of file From 63afc2b705aaae944a75b826e00aac108217c469 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Mon, 11 Aug 2025 12:22:52 -0500 Subject: [PATCH 11/11] add explosion of stuff --- docs/docstrings.md | 9 +++++---- docs/index.md | 9 +++++++-- mkdocs.yml | 18 +++++++++++++++++- 3 files changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/docstrings.md b/docs/docstrings.md index 2d4eda7..62c1b40 100644 --- a/docs/docstrings.md +++ b/docs/docstrings.md @@ -8,13 +8,11 @@ However, my biggest caution is that code documentation can often be ignored and Documenting code has many perspectives, here are a few perspectives that I have appreciated over time. -```{tip} -Sections have an opinionated order from most to least important. -``` +!!! 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. @@ -79,6 +77,7 @@ def threshold_otsu_minimum( ------- threshold : int | float Threshold value + """ ... ``` @@ -96,6 +95,8 @@ def test_threshold_otsu_with_minimum(): 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. diff --git a/docs/index.md b/docs/index.md index 000ea34..9235cea 100644 --- a/docs/index.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 9a2d90a..dc6f0a4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,20 @@ site_name: 2025 URSSI Docs site_url: https://timmonko.github.io/urssi-docs/ theme: - name: material \ No newline at end of file + 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 \ No newline at end of file