Upgrade docs

.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

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",

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.

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

CONTRIBUTING.md → 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

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.

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

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 <https://github.com/bioio-devs/bioio/issues>`_.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Contents:
+
+   Contributing <CONTRIBUTING>
+   Code of Conduct <CODE_OF_CONDUCT>
+   Governance Model <GOVERNANCE>
+   Mission and Values <MISSION_AND_VALUES>

docs/index.rst

@@ -7,8 +7,28 @@ Welcome to bioio's documentation!
    :caption: Contents:
 
    Overview <self>
-   installation
-   Package modules <modules>
-   contributing
+   Installation <INSTALLATION>
+   Full API Reference <modules>
+   Developer Resources <developer_resources>
+   Changelog <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`

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",