Add docs

* Add faqtory, and faqtory github action and common questions to FAQ

* Add link to FAQ

* Initial docs rewrite

* pre-commit fix

* validation script

* Initial validation script

This introduces an initial validation script that spits out a very
verbose error message if a TOML file cannot be parsed.

This also changes CLI arguments slightly to separate entry points that
use just logging (validate) and those that want to connect to a device
(targets, unblock-all).

* Add exceptiongroup parsing

* Add validation script and tests

* Guppy is not py3.11 compatible 🫠

* Add the updated pyproject.toml

* Force add TOML files for tests

* Add doctests to pytest, move exception reporter to _utils.py

* Check plugins on pass tests

* Import guard for BaseExceptionGroup

* Clarify target parsing names, remove duplication in validation tests

* Exempt labels from stale bo

* Exempt enhancement and bug issue labels from stale bot

* Merge in origin/refactor

* Fix Readfish validate fails

Typo in variable name

* Add faqtory, and faqtory github action and common questions to FAQ

* Add link to FAQ

* Initial docs rewrite

* pre-commit fix

* Merge in origin/refactor

* Update README.md, add detail sections

* Added back closing detail tag after messy rebase/merge combo

* Update README.md

* Fix drop down stylings

Switch to h* tags rather than style CSS, which I forgot is sanitised out in GitHub

* Update toml.md to reflect refactor readfish

* Add development.yml file

* Write development guide

* Update TOML.md

* Fix typo in docstring lol

* Add workflow to push to gh_pages maybe

* Update pages markdown
Add style to READMEs
Section readmes

* Doc strings

* Set readfish version and release

* Try pip install for pre-build command

* Apt-get install git in docs container

* Pivot from sphinx-build
Out dated and unmaintained sad

* Sudo install git

* Enable caching of packages

* test with docs branch

* Whoops typo on docs path

* Documentation for targets.py

* Docstrings

* Update rst docs

* Update black revision on precommit config
Had issue with pre commit revision clashing with lint github action black version
This brings pre commit to match the black version
we should pin the version on the lint yaml

* RST ALL FUNCTIONS(ISH) and first draft docs

* types on Read

* Modifications to text and addition of minimal ToDos for editing.

* Symlink to fix paths in README
this allows rendering images in generated docs

* Change paths to images

* Add autosection label extension
Better betwixt docs referencing

* Add seperately toml section in Index,
Fixes link

* Typo

* More typing types

* Adressed todos

* Add relative Symlink

* Typos and small docs sections updates

* Update docs - all looks good for me

* Documentation edits

* Documentation edits

* Add relative Symlink

* Resolve conflicts

Typos and small docs sections updates

* Resolvinf conflicts

Update docs - all looks good for me

* Fix broken install

* Fix cryptic typing error

* Small changes
Adding back in the development installation in README.md
Adding an example of multiple barcoding kits.

* Small updatesd

* Clarify getting started

---------

Co-authored-by: Adoni5 <[email protected]>
Co-authored-by: Matt Loose <[email protected]>

.github/CONTRIBUTING.md

@@ -0,0 +1,150 @@
+# How To Contribute
+
+Thank you for considering contributing to *readfish*!
+
+This document intends to make contribution more accessible by codifying tribal knowledge and expectations.
+Don't be afraid to open half-finished PRs, and ask questions if something is unclear!
+
+
+## Workflow
+
+- No contribution is too small!
+- Try to limit each pull request to *one* change only.
+- Since we tend to squash on merge, it's up to you how you handle updates to the `main` branch.
+  Whether you prefer to rebase on `main` or merge `main` into your branch, do whatever is more comfortable for you.
+- *Always* add tests and docs for your code.
+  This is a hard rule; patches with missing tests or documentation won't be merged.
+- Make sure your changes pass our CI.
+  You won't get any feedback until it's green unless you ask for it.
+- Once you've addressed review feedback, make sure to bump the pull request with a short note, so we know you're done.
+
+
+## Local Development Environment
+
+You’ll probably want a traditional environment as well.
+We highly recommend to develop using the latest Python release because we try to take advantage of modern features whenever possible.
+Also, running [*pre-commit*] later on will require the latest Python version.
+
+First [fork](https://github.com/LooseLab/readfish/fork) the repository on GitHub.
+
+Clone the fork to your computer:
+
+```console
+git clone [email protected]:<your-username>/readfish.git
+```
+
+Then add the *reafish* repository as *upstream* remote:
+
+```console
+git remote add -t main -m main --tags upstream https://github.com/LooseLab/readfish.git
+```
+
+The next step is to sync your local copy with the upstream repository:
+
+```console
+cd readfish
+git fetch upstream
+```
+
+```console
+python -m venv venv --prompt readfish --upgrade-deps
+source ./venv/bin/activate
+python -m pip install -e '.[all,dev]'
+```
+
+Documentation can be built:
+
+```console
+cd docs
+make html
+```
+
+The built documentation can then be found in `docs/_build/html/` and served:
+
+```console
+python -m http.server 9999
+```
+
+then visit [127.0.0.1:9999](127.0.0.1:9999).
+
+If you update or write an FAQ entry those are automatically built using [FAQtory]:
+
+```console
+faqtory build -c .github/faq.yml
+```
+
+To file a pull request, create a new branch on top of the upstream repository's `main` branch:
+
+```console
+git fetch upstream
+git checkout -b my_branch upstream/main
+```
+
+Make your changes, push them to your fork (the remote *origin*):
+
+```console
+git push -u origin
+```
+
+and publish the PR in GitHub's web interface!
+
+After your pull request is merged and the branch is no longer needed, delete it:
+
+```console
+git checkout main
+git push --delete origin my_branch && git branch -D my_branch
+```
+
+Before starting to work on your next pull request, run the following command to sync your local repository with the remote *upstream*:
+
+```console
+git fetch upstream -u main:main
+```
+
+---
+
+To avoid committing code that violates our style guide, we strongly advise you to install [*pre-commit*] and its hooks:
+
+```console
+pre-commit install
+```
+
+You can run:
+
+```console
+pre-commit run --all-files
+```
+
+This will run on CI, but it's more comfortable to run it locally and *git* catching avoidable errors.
+
+
+## Documentation
+
+- Use [semantic newlines] in [*reStructuredText*][rst] and [*Markdown*][md] files (files ending in `.rst` and `.md`):
+
+  ```rst
+  This is a sentence.
+  This is another sentence.
+  ```
+
+- If you start a new section, add two blank lines before and one blank line after the header, except if two headers follow immediately after each other:
+
+  ```rst
+  Last line of previous section.
+
+
+  Header of New Top Section
+  -------------------------
+
+  Header of New Section
+  ^^^^^^^^^^^^^^^^^^^^^
+
+  First line of new section.
+  ```
+
+
+[semantic newlines]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
+[rst]: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html
+[md]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
+[*pre-commit*]: https://pre-commit.com/
+[FAQtory]: https://github.com/willmcgugan/faqtory

.github/faq.yml

@@ -0,0 +1,7 @@
+# FAQtory settings
+
+faq_url: "https://github.com/willmcgugan/faqtory/blob/main/FAQ.md" # Replace this with the URL to your FAQ.md!
+
+questions_path: "./docs/questions" # Where questions should be stored
+output_path: "./docs/FAQ.md" # Where FAQ.md should be generated
+templates_path: "./.github/faq" # Path to templates

.github/faq/FAQ.md

@@ -0,0 +1,20 @@
+
+# Frequently Asked Questions
+
+{%- for question in questions %}
+- [{{ question.title }}](#{{ question.slug }})
+{%- endfor %}
+
+
+{%- for question in questions %}
+
+<a name="{{ question.slug }}"></a>
+## {{ question.title }}
+
+{{ question.body }}
+
+{%- endfor %}
+
+<hr>
+
+Generated by [FAQtory](https://github.com/willmcgugan/faqtory)

.github/faq/suggest.md

@@ -0,0 +1,20 @@
+{%- if questions -%}
+{% if questions|length == 1 %}
+We found the following entry in the [FAQ]({{ faq_url }}) which you may find helpful:
+{%- else %}
+We found the following entries in the [FAQ]({{ faq_url }}) which you may find helpful:
+{%- endif %}
+
+{% for question in questions %}
+- [{{ question.title }}]({{ faq_url }}#{{ question.slug }})
+{%- endfor %}
+
+Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.
+
+{%- else -%}
+Thank you for your issue. Give us a little time to review it.
+
+PS. You might want to check the [FAQ]({{ faq_url }}) if you haven't done so already.
+{%- endif %}
+
+This is an automated reply, generated by [FAQtory](https://github.com/willmcgugan/faqtory)

.github/workflows/faqtory.yml

@@ -0,0 +1,29 @@
+name: issues
+on:
+  issues:
+    types: [opened]
+jobs:
+  add-comment:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: main
+      - name: Install FAQtory
+        run: pip install FAQtory
+      - name: Run Suggest
+        env:
+          TITLE: ${{ github.event.issue.title }}
+        run: faqtory suggest "$TITLE" > suggest.md
+      - name: Read suggest.md
+        id: suggest
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./suggest.md
+      - name: Suggest FAQ
+        uses: peter-evans/create-or-update-comment@a35cf36e5301d70b76f316e867e7788a55a31dae
+        with:
+          issue-number: ${{ github.event.issue.number }}
+          body: ${{ steps.suggest.outputs.content }}

.github/workflows/gh_pages.yml

@@ -0,0 +1,52 @@
+name: gh_pages
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.8'
+
+      - name: Upgrade pip
+        run: |
+          # install pip=>20.1 to use "pip cache dir"
+          python3 -m pip install --upgrade pip
+
+      - name: Install git
+        run: |
+          # install pip=>20.1 to use "pip cache dir"
+          sudo apt-get update -y && sudo apt-get install -y git
+
+      - name: Get pip cache dir
+        id: pip-cache
+        run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.pip-cache.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: python3 -m pip install .[docs]
+
+      - run: cd docs && make html
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/docs'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html/

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 # PyCharm
 .idea/
 *.toml
+
+# Other
+.DS_Store

.pre-commit-config.yaml

@@ -1,18 +1,35 @@
 repos:
 
   - repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 23.3.0
     hooks:
       - id: black
         name: black (python)
-        args:
-          - '--target-version=py38'
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.3.0
     hooks:
       - id: end-of-file-fixer
-        exclude: '(\.patch|\.diff|\.fasta$|\.fastq$|\.sam$|\.rbt$|\.bit$|target/)'
+        exclude: '^.+\.(patch|diff|fasta|fastq|sam|rbt|bit|target|svg)$'
       - id: trailing-whitespace
-        exclude: '(target/|\.patch|\.diff|\.fasta$|\.fastq$|\.sam$|\.rbt$|\.bit$)'
+        exclude: '^.+\.(patch|diff|fasta|fastq|sam|rbt|bit|target|svg)$'
       - id: check-ast
       - id: check-toml
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.0.276
+    hooks:
+      - id: ruff
+  - repo: local
+    hooks:
+      - id: ReadFish-checker
+        name: disallow "ReadFish"
+        types: [text]
+        exclude: '^.pre-commit-config.yaml$'
+        entry: 'Read[ _-]*Fish'
+        language: pygrep
+      - id: read-fish-checker
+        name: disallow "read fish"
+        types: [text]
+        exclude: '^.pre-commit-config.yaml$'
+        entry: '(?i)read fish'
+        language: pygrep
+        files: .+\.(yml|yaml|py|md|rst)