From 594fa90dcd581806a337a0a16396990945cc545f Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Fri, 27 Oct 2023 16:56:37 -0700 Subject: [PATCH] Upgrade docs --- .github/workflows/docs.yml | 1 + bioio/writers/timeseries_writer.py | 6 +- bioio/writers/two_d_writer.py | 8 +-- docs/CODE_OF_CONDUCT.md | 73 +++++++++++++++++++ CONTRIBUTING.md => docs/CONTRIBUTING.md | 30 +++++--- docs/GOVERNANCE.md | 93 +++++++++++++++++++++++++ docs/MISSION_AND_VALUES.md | 82 ++++++++++++++++++++++ docs/developer_resources.rst | 16 +++++ docs/index.rst | 26 ++++++- pyproject.toml | 1 + 10 files changed, 312 insertions(+), 24 deletions(-) create mode 100644 docs/CODE_OF_CONDUCT.md rename CONTRIBUTING.md => docs/CONTRIBUTING.md (72%) create mode 100644 docs/GOVERNANCE.md create mode 100644 docs/MISSION_AND_VALUES.md create mode 100644 docs/developer_resources.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e88e059..8e64dc6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,6 +24,7 @@ jobs: pip install .[docs] - name: Generate Docs run: | + gitchangelog just generate-docs touch docs/_build/.nojekyll - name: Publish Docs diff --git a/bioio/writers/timeseries_writer.py b/bioio/writers/timeseries_writer.py index 2b85656..dd6c94f 100644 --- a/bioio/writers/timeseries_writer.py +++ b/bioio/writers/timeseries_writer.py @@ -19,10 +19,6 @@ class TimeseriesWriter(Writer): """ A writer for timeseries Greyscale, RGB, or RGBA image data. Primarily directed at formats: "gif", "mp4", "mkv", etc. - - Notes - ----- - To use this writer, install with: `pip install aicsimageio[base-imageio]`. """ _TIMEPOINT_DIMENSIONS = [ @@ -124,7 +120,7 @@ def save( a non-time dimension. For example, creating a timeseries image where each frame is a Z-plane from a source volumetric image as seen below. - >>> image = AICSImageIO("some_z_stack.ome.tiff") + >>> image = BioImage("some_z_stack.ome.tiff") ... TimeseriesWriter.save( ... data=image.get_image_data("ZYX", T=0, C=0), ... uri="some_z_stack.mp4", diff --git a/bioio/writers/two_d_writer.py b/bioio/writers/two_d_writer.py index eca56b0..803adc6 100644 --- a/bioio/writers/two_d_writer.py +++ b/bioio/writers/two_d_writer.py @@ -18,10 +18,6 @@ class TwoDWriter(Writer): Primarily directed at formats: "png", "jpg", etc. This is primarily a passthrough to imageio.imwrite. - - Notes - ----- - To use this writer, install with: `pip install aicsimageio[base-imageio]`. """ _PLANE_DIMENSIONS = [ @@ -90,8 +86,8 @@ def save( The dimension order of the provided data. Default: None. Based off the number of dimensions, will assume the dimensions similar to how - aicsimageio.readers.default_reader.DefaultReader reads in - data. That is, two dimensions: YX and three dimensions: YXS. + https://github.com/bioio-devs/bioio-imageio/blob/main/bioio_imageio/reader.py + reads in data. That is, two dimensions: YX and three dimensions: YXS. fs_kwargs: Dict[str, Any] Any specific keyword arguments to pass down to the fsspec created filesystem. diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b7f7e5e --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers 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, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting any of the contributors from the Allen Institute and +we will attempt to resolve the issues with respect and dignity. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 72% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md index ce440df..f900bb4 100644 --- a/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -79,15 +79,25 @@ Available recipes: ## Deploying A reminder for the maintainers on how to deploy. -Make sure the main branch is checked out and all desired changes -are merged. Then run: +1) Make sure all your changes are committed and merged into main. +2) Make sure branch is clean: + ```bash + git checkout main + git stash + git pull + ``` +3) Create tag and push new version to GitHub like so: + ```bash + just tag-for-release "vX.Y.Z" + just release + ``` +4) Wait for a [GitHub Action](https://github.com/bioio-devs/bioio/actions) to automatically publish to [PyPI](https://pypi.org/project/bioio/) +5) [Create GitHub release](https://github.com/bioio-devs/bioio/releases/new) for the corresponding version created. -```bash -just tag-for-release "vX.Y.Z" -just release -``` + 6a) Select tag for version created + + 6b) Ensure GitHub automatically generates releases notes ([click "Generate Release Notes"](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)) + + 6c) Double check format is similar to previous releases -The presence of a tag starting with "v" will trigger the `publish` step in the -main github workflow, which will build the package and upload it to PyPI. The -version will be injected into the package metadata by -[`setuptools-scm`](https://github.com/pypa/setuptools_scm) + 6d) Publish release diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md new file mode 100644 index 0000000..3fdfc2d --- /dev/null +++ b/docs/GOVERNANCE.md @@ -0,0 +1,93 @@ +# Governance Model + +## Abstract + +The purpose of this document is to formalize the governance process used by the +`bioio` project, to clarify how decisions are made and how the various +elements of our community interact. + +This is a consensus-based community project. Anyone with an interest in the +project can join the community, contribute to the project design, and +participate in the decision making process. This document describes how that +participation takes place, how to find consensus, and how deadlocks are +resolved. + +## Roles And Responsibilities + +### The Community + +The bioio community consists of anyone using or working with the project +in any way. + +### Contributors + +A community member can become a contributor by interacting directly with the +project in concrete ways, such as: + +- proposing a change to the code via a + [GitHub pull request](https://github.com/bioio-devs/bioio/pulls); +- reporting issues on our + [GitHub issues page](https://github.com/bioio-devs/bioio/issues); +- proposing a change to the documentation via a + [GitHub pull request](https://github.com/bioio-devs/bioio/pulls); +- discussing the design of bioio on existing + [issues](https://github.com/bioio-devs/bioio/issues) and / or + [pull requests](https://github.com/bioio-devs/bioio/pulls); +- reviewing [open pull requests](https://github.com/bioio-devs/bioio/pulls) + +among other possibilities. Any community member can become a contributor, and +all are encouraged to do so. By contributing to the project, community members +can directly help to shape its future. + +Contributors are encouraged to read the [contributing guide](./CONTRIBUTING.md). + +### Core developers + +Core developers are community members that have demonstrated continued +commitment to the project through ongoing contributions. They +have shown they can be trusted to maintain bioio with care. Becoming a +core developer allows contributors to merge approved pull requests, cast votes +for and against merging a pull-request, and be involved in deciding major +changes to the API, and thereby more easily carry on with their project related +activities. Core developers appear as team members on our +[@bioio-devs/trusted-developers](https://github.com/orgs/bioio-devs/teams/trusted-developers) +GitHub team. Core developers are asked to review code contributions. New core +developers can be nominated by any existing core developer. + +### Steering Council + +The Steering Council (SC) members are core developers who have additional +responsibilities to ensure the smooth running of the project. SC members are +expected to participate in strategic planning, approve changes to the +governance model. The purpose of the SC is to ensure smooth progress from the big +picture perspective. Changes that impact the full project require analysis informed by +long experience with both the project and the larger ecosystem. When the core +developer community (including the SC members) fails to reach such a consensus +in a reasonable time-frame, the SC is the entity that resolves the issue. + +The steering council is currently fixed to only include members directly from Allen +Institute for Cell Science. This may be changed in the future, but this results in the +steering council currently consisting of: + +- [Eva Maxfield Brown](https://github.com/evamaxfield) +- [Daniel Toloudis](https://github.com/toloudis) + +New members are added by nomination by a core developer. Nominees should have +demonstrated long-term, continued commitment to the project and its +[mission and values](./MISSION_AND_VALUES.md). + +## Decision Making Process + +Decisions about the future of the project are made through discussion with all +members of the community. All non-sensitive project management discussion takes +place on the [issue tracker](https://github.com/bioio-devs/bioio/issues). +Occasionally, sensitive discussion may occur through a private core developer channel. + +Decisions should be made in accordance with the +[mission and values](./MISSION_AND_VALUES.md) of the bioio project. + +bioio uses a “consensus seeking” process for making decisions. The group +tries to find a resolution that has no open objections among core developers. +Core developers are expected to distinguish between fundamental objections to a +proposal and minor perceived flaws that they can live with, and not hold up the +decision-making process for the latter. diff --git a/docs/MISSION_AND_VALUES.md b/docs/MISSION_AND_VALUES.md new file mode 100644 index 0000000..2c56081 --- /dev/null +++ b/docs/MISSION_AND_VALUES.md @@ -0,0 +1,82 @@ +# Mission and Values + +This document is meant to help guide decisions about the future of bioio, be it +in terms of whether to accept new functionality, changes to existing functionality, +changes to package administrative tasks, etc. It serves as a reference for core +developers in guiding their work, and, as an introduction for newcomers who want to +learn where the project is headed and what the team's values are. You can also learn +how the project is managed by looking at our [governance model](./GOVERNANCE.md). + +## Mission + +bioio aims to provide a **consistent intuitive API for reading in or out-of-memory +image pixel data and metadata** for the many existing proprietary microscopy file +formats, and, an **easy-to-use API for converting from proprietary file formats to an +open, common, standard** -- all using either language agnostic or pure Python tooling. + +In short: +> bioio provides a method to fully read and convert from an existing proprietary +> microscopy file format to, or _emulate_, a Python representation of the community +> standard metadata model regardless of image size, format, or location. + +(The current community standard for microscopy images is the +[Open Microscopy Environment](https://www.openmicroscopy.org/)) + +We hope to accomplish this by: +* being **easy to use and install**. We will take extra care to ensure that this library +is easy to use and fully installable on Windows, Mac-OS, and Ubuntu. +* being **well-documented** with our entire API having up-to-date, useful docstrings +and additionally providing examples of more complex use-cases when possible. +* providing a **consistent and stable API** to users by following +[semantic versioning](https://semver.org/) and limiting the amount of breaking changes +introduced unless necessary for the future robustness or scalability of the library. +* sustaining **comparable or better performance when compared to more tailored file +format reading libraries**. We will regularly run benchmarks utilizing a set of varied +size images from all the file formats the library is capable of reading. +* **working closely with the microscopy community** while deciding on standards and best +practices for open, accessible, file formats and imaging and in deciding which +proprietary file formats and metadata selection are in need of support. + +## Values +* We are **inclusive**. We welcome and mentor newcomers who are making their first +contribution and strive to grow our most dedicated contributors into core developers. We +have a [Code of Conduct](./CODE_OF_CONDUCT.md) to ensure that the bioio remains +a welcoming place for all. +* We are **community-driven**. We respond to feature requests and proposals on our +[issue tracker](https://github.com/bioio-devs/bioio/issues) and make +decisions that are driven by our user's requirements. +* We focus on **file IO and metadata conversion**, leaving image analysis functionality +and visualization to other libraries. +* We aim to **develop new methods of metadata extraction and conversion**, instead of +duplicating existing, or porting, from other libraries primarily by creating **language +agnostic methods** for metadata manipulation. +* We value **simple, readable implementations**. Readable code that is easy to +understand, for newcomers and maintainers alike, makes it easier to contribute new code +as well as prevent bugs. +* We value **education and documentation**. All functions should have docstrings, +preferably with examples, and major functionality should be explained in our tutorials. +Core developers can take an active role in finishing documentation examples. +* We **minimize [magic](https://en.wikipedia.org/wiki/Magic_(programming))** and always +provide a way for users to opt out of magical behaviour and guessing by providing +explicit ways to control functionality. + +## Acknowledgments +We share a lot of our mission and values with the `napari` project, and acknowledge the +influence of their mission and values statement on this document. + +Additionally, much of the work produced for this library is built on the shoulders of +giants. Notably: +* [Christoph Gohlke](https://www.lfd.uci.edu/~gohlke/) -- maintainer of `tifffile`, +`czifile`, and the `imagecodecs` libraries +* [Paul Watkins](https://github.com/elhuhdron) -- original creator of `pylibczi` +* [OME and Bio-Formats Team](https://github.com/ome/bioformats) -- proprietary +microscopy file format conversion and standards development +* [Python-Bio-Formats Team](https://github.com/CellProfiler/python-bioformats) -- +Python Java Bridge for Bio-Formats and original implementations of OME Python +representation +* [imageio Team](https://github.com/imageio/imageio) -- robust, expansive, cross +platform image reading +* [Dask Team](https://dask.org/) -- delayed and out-of-memory parallel array +manipulation +* [xarray Team](https://github.com/pydata/xarray) -- coordinate and metadata attached +array handling and manipulation diff --git a/docs/developer_resources.rst b/docs/developer_resources.rst new file mode 100644 index 0000000..489db0c --- /dev/null +++ b/docs/developer_resources.rst @@ -0,0 +1,16 @@ +Developer Resources +=================== + +A compiled list of resources for new and existing developers and maintainers of the +library. If you believe a document or information is missing please check our +`issue tracker `_. + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Contents: + + Contributing + Code of Conduct + Governance Model + Mission and Values diff --git a/docs/index.rst b/docs/index.rst index 6ce6de6..698f30e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,8 +7,28 @@ Welcome to bioio's documentation! :caption: Contents: Overview - installation - Package modules - contributing + Installation + Full API Reference + Developer Resources + Changelog .. mdinclude:: ../README.md + +Specific Doc Pages +================== + +.. autosummary:: + :toctree: + :caption: Important Classes: + + bioio.BioImage + bioio.writers.OmeTiffWriter + bioio.writers.OmeZarrWriter + bioio.writers.TimeseriesWriter + bioio.writers.TwoDWriter + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/pyproject.toml b/pyproject.toml index e4c9ae1..f958587 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,7 @@ test = [ ] docs = [ # Sphinx + Doc Gen + Styling + "gitchangelog>=3.0.4", "m2r2>=0.2.7", "Sphinx>=4.0.0", "furo>=2022.4.7",