diff --git a/docs/docstrings.md b/docs/docstrings.md new file mode 100644 index 0000000..62c1b40 --- /dev/null +++ b/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 :) 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/docs/repo_setup.md b/docs/repo_setup.md index d54ea65..c2fe3d3 100644 --- a/docs/repo_setup.md +++ b/docs/repo_setup.md @@ -4,4 +4,4 @@ 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) \ No newline at end of file +5. [Update pyproject.toml](https://www.pyopensci.org/python-package-guide/tutorials/pyproject-toml.html) 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 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