Add docsite (#73)

* add docs handling capabilities

* drop python 3.8; linting

* update theme and customize

* linting

* add templates

* add additional dev guidance on docs

* linting

* remove and ignore build files; file comment

Co-Authored-By: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

* add documentation to template files

* remove testing step from gh actions job

---------

Co-authored-by: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

.github/workflows/publish-docs.yml

@@ -0,0 +1,43 @@
+---
+# used for publishing documentation on push to main or published release
+name: publish docs
+
+on:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Setup for poetry
+        run: |
+          python -m pip install poetry poetry-dynamic-versioning
+      - name: poetry deps
+        run: poetry install
+      - name: Build documentation
+        run: |
+          mkdir pages
+          touch pages/.nojekyll
+          cd docs
+          poetry run sphinx-multiversion src build
+          cp -r build/* ../pages/
+      - name: Add index redirector to latest docs
+        run: |
+          cp docs/redirector.html pages/index.html
+      - name: Deploy documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: pages
+          folder: pages

.gitignore

@@ -143,4 +143,8 @@ cython_debug/
 
 .DS_Store
 
+# data used for testing but not yet ready to be checked in
 tests/data/cytotable/Nuclear_speckles
+
+# jupyter notebook build files from myst-nb
+docs/jupyter_execute

CODE_OF_CONDUCT.md

@@ -1,132 +1,3 @@
 # 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, socioeconomic 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 community leaders responsible for enforcement.
-Please open a [new security advisory notice](https://github.com/WayScience/coSMicQC/security/advisories/new) (using defaults or "n/a" where unable to fill in the form) to privately notify us of any incidents of this nature.
-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].
-
-[faq]: https://www.contributor-covenant.org/faq
-[homepage]: https://www.contributor-covenant.org
-[mozilla coc]: https://github.com/mozilla/diversity
-[translations]: https://www.contributor-covenant.org/translations
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+Please see our full code of conduct at https://WayScience.github.io/coSMicQC/main/code_of_conduct

CONTRIBUTING.md

@@ -1,116 +1,3 @@
 # Contributing
 
-First of all, thank you so much for contributing! 🎉 💯
-
-This document contains guidelines on how to most effectively contribute within this repository.
-
-If you are stuck, please feel free to ask any questions or ask for help.
-
-## Code of conduct
-
-This project is governed by our [code of conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to community leaders responsible for enforcement.
-Please open a [new security advisory notice](https://github.com/WayScience/coSMicQC/security/advisories/new) (using defaults or "n/a" where unable to fill in the form) to privately notify us of any incidents of this nature.
-
-## Development
-
-This project leverages development environments managed by Python [Poetry](https://python-poetry.org/).
-We leverage interactions with the Docker through Python to achieve reproducible results through containers.
-We use [pytest](https://docs.pytest.org/) for testing and [GitHub actions](https://docs.github.com/en/actions) for automated tests.
-
-### Development setup
-
-Perform the following steps to setup a Python development environment.
-
-1. [Install Python](https://www.python.org/downloads/)
-1. [Install Poetry](https://python-poetry.org/docs/#installation)
-1. [Install Poetry Environment](https://python-poetry.org/docs/basic-usage/#installing-dependencies): `poetry install`
-
-### Linting
-
-Work added to this project is automatically checked using [pre-commit](https://pre-commit.com/) via [GitHub Actions](https://docs.github.com/en/actions).
-Pre-commit can work alongside your local [git with git-hooks](https://pre-commit.com/index.html#3-install-the-git-hook-scripts)
-
-After [installing pre-commit](https://pre-commit.com/#installation) within your development environment, the following command also can perform the same checks within your local development environment:
-
-```sh
-% pre-commit run --all-files
-```
-
-We use these same checks within our automated tests which are managed by [GitHub Actions workflows](https://docs.github.com/en/actions/using-workflows).
-These automated tests generally must pass in order to merge work into this repository.
-
-### Testing
-
-Work added to this project is automatically tested using [pytest](https://docs.pytest.org/) via [GitHub Actions](https://docs.github.com/en/actions).
-Pytest is installed through the Poetry environment for this project.
-We recommend testing your work before opening pull requests with proposed changes.
-
-You can run pytest on your work using the following example:
-
-```sh
-% poetry run pytest
-```
-
-## Making changes to this repository
-
-We welcome anyone to use [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) (requires a GitHub login) or create [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) (to directly make changes within this repository) to modify content found within this repository.
-
-Specifically, there are several ways to suggest or make changes to this repository:
-
-1. Open a GitHub issue: https://github.com/WayScience/coSMicQC/issues
-1. Create a pull request from a forked branch of the repository
-
-### Creating a pull request
-
-### Pull requests
-
-After you’ve decided to contribute code and have written it up, please file a pull request.
-We specifically follow a [forked pull request model](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork).
-Please create a fork of this repository, clone the fork, and then create a new, feature-specific branch.
-Once you make the necessary changes on this branch, you should file a pull request to incorporate your changes into this (fork upstream) repository.
-
-The content and description of your pull request are directly related to the speed at which we are able to review, approve, and merge your contribution.
-To ensure an efficient review process please perform the following steps:
-
-1. Follow all instructions in the [pull request template](.github/PULL_REQUEST_TEMPLATE.md)
-1. Triple check that your pull request is adding _one_ specific feature or additional group of content.
-   Small, bite-sized pull requests move so much faster than large pull requests.
-1. After submitting your pull request, ensure that your contribution passes all status checks (e.g. passes all tests)
-
-Pull request review and approval is required by at least one project maintainer to merge.
-We will do our best to review the code addition in a timely fashion.
-Ensuring that you follow all steps above will increase our speed and ability to review.
-We will check for accuracy, style, code coverage, and scope.
-
-## Versioning
-
-We use [`poetry-dynamic-versioning`](https://github.com/mtkennerly/poetry-dynamic-versioning) to help version this software through [`PEP 440`](https://peps.python.org/pep-0440/) standards.
-Configuration for versioning is found within the `pyproject.toml` file.
-All builds for packages include dynamic version data to help label distinct versions of the software.
-`poetry-dynamic-versioning` uses `git` tags to help distinguish version data.
-We also use the `__init__.py` file as a place to persist the version data for occaissions where the `git` history is unavailable or unwanted.
-
-The following command is used to add `poetry-dynamic-versioning` to Poetry for use with this project: `poetry self add "poetry-dynamic-versioning[plugin]"`.
-Versioning for the project is intended to align with GitHub Releases which provide `git` tag capabilities.
-
-### Releases
-
-We publish source code by using [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) available [here](https://github.com/wayscience/cosmicqc/releases).
-We publish a related Python package through the [Python Packaging Index (PyPI)](https://pypi.org/) available [here](https://pypi.org/project/cosmicqc/).
-
-#### Release Publishing Process
-
-Several manual and automated steps are involved with publishing coSMicQC releases.
-See below for an overview of how this works.
-
-Notes about [semantic version](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning) (semver) specifications:
-coSMicQC version specifications are controlled through [`poetry-dynamic-versioning`](https://github.com/mtkennerly/poetry-dynamic-versioning) which leverages [`dunamai`](https://github.com/mtkennerly/dunamai) to create version data based on [git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and commits.
-coSMicQC release git tags are automatically applied through [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) and related inferred changes from [`release-drafter`](https://github.com/release-drafter/release-drafter).
-
-1. Open a pull request and use a repository label for `release-<semver release type>` to label the pull request for visibility with [`release-drafter`](https://github.com/release-drafter/release-drafter) (for example, see [coSMicQC#24](https://github.com/wayscience/cosmicqc/pull/24) as a reference of a semver patch update).
-1. On merging the pull request for the release, a [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows) defined in `draft-release.yml` leveraging [`release-drafter`](https://github.com/release-drafter/release-drafter) will draft a release for maintainers.
-1. The draft GitHub release will include a version tag based on the GitHub PR label applied and `release-drafter`.
-1. Make modifications as necessary to the draft GitHub release, then publish the release (the draft release does not normally need additional modifications).
-1. On publishing the release, another GitHub Actions workflow defined in `publish-pypi.yml` will run to build and deploy the Python package to PyPI (utilizing the earlier modified `pyproject.toml` semantic version reference for labeling the release).
+Please see our [contributing](https://WayScience.github.io/coSMicQC/main/contributing) documentation for more details on contributions, development, and testing.

README.md

@@ -35,7 +35,7 @@ pip install git+https://github.com/WayScience/coSMicQC.git
 
 ## Contributing, Development, and Testing
 
-Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more details on contributions, development, and testing.
+Please see our [contributing](https://WayScience.github.io/coSMicQC/main/contributing) documentation for more details on contributions, development, and testing.
 
 ## References
 

docs/src/_static/custom.css

@@ -0,0 +1,39 @@
+div.cell_output table {
+    border: none;
+    border-collapse: collapse;
+    border-spacing: 0;
+    color: black;
+    font-size: 1em;
+    table-layout: fixed;
+    background: white;
+    overflow: scroll;
+    max-width: 600px;
+}
+
+.pt-5, .py-5 {
+    padding-top: 1rem !important;
+}
+
+section {
+    margin-top: 0rem;
+    margin-bottom: 2rem;
+}
+
+.cell_input div.highlight, .cell_output pre, .cell_input pre, .cell_output .output {
+    border: none;
+    box-shadow: none;
+    overflow: auto;
+}
+
+#main img{
+    max-width:600px;
+}
+
+.page-toc {
+    font-size: .875rem;
+    padding-top: 0 !important;
+    color: #494949;
+    max-height: 100vh;
+    overflow: hidden auto;
+    word-break: break-all;
+}