Merge pull request #66 from tekktrik/dev/docs

Update API to match circup, refactor backend

.github/workflows/push.yml

@@ -14,6 +14,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
+      max-parallel: 3
       matrix:
         py-version: [
           "3.8",
@@ -41,6 +42,12 @@ jobs:
       - name: Run pre-commit via make
         run: |
           make check
+      - name: Test packaging
+        run: |
+          python -m build
+      - name: Test documentation
+        run: |
+          make docs
       - name: Prepare tests
         run : |
           make test-prep
@@ -62,6 +69,3 @@ jobs:
           fail_ci_if_error: true
           file: coverage_${{ matrix.os }}_${{ matrix.py-version }}.xml
           flags: "${{ matrix.os }}-py-${{ matrix.py-version }}"
-      - name: Test packaging
-        run: |
-          python -m build

.gitignore

@@ -142,3 +142,6 @@ testmount/
 # Test related
 tests/backup/
 tests/sandbox/
+
+# Sphinx specific
+_build/

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2022 Alec Delaney, for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+  - requirements: requirements-dev.txt

LICENSES/MIT.txt

@@ -1,4 +1,6 @@
-MIT License Copyright (c) <year> <copyright holders>
+MIT License
+
+Copyright (c) <year> <copyright holders>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSES/Unlicense.txt

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

Makefile

@@ -14,6 +14,13 @@ format:
 check:
 	@pre-commit run --all-files
 
+.PHONY: docs
+docs:
+	@sphinx-build -E -W -b html docs docs/_build
+
+.PHONY: prepare
+prepare: check test docs
+
 .PHONY: test-prep
 test-prep:
 ifeq "$(OS)" "Windows_NT"

README.rst

@@ -1,10 +1,18 @@
+..
+   SPDX-FileCopyrightText: 2022 Alec Delaney, for Adafruit Industries
+   SPDX-License-Identifier: MIT
+
 circfirm
 --------
 
 .. image:: https://img.shields.io/pypi/pyversions/circfirm
    :target: https://pypi.org/project/circfirm/
    :alt: PyPI - Python Version
 
+.. image:: https://readthedocs.org/projects/circfirm/badge/?version=latest
+    :target: https://circfirm.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
 .. image:: https://img.shields.io/github/actions/workflow/status/tekktrik/circfirm/push.yml
    :target: https://github.com/tekktrik/circfirm/actions
    :alt: GitHub Actions Workflow Status
@@ -39,8 +47,8 @@ You can also just use ``pip`` to install it, if the dependencies won't cause iss
 
     pip install circfirm
 
-Usage
-=====
+Example Usage
+=============
 
 The follow commands show some of the functionality of ``circfirm``:
 
@@ -56,7 +64,7 @@ The follow commands show some of the functionality of ``circfirm``:
     circfirm cache list
 
     # List all the cached CircuitPython versions for a speciic board
-    circfirm cache list --board feather_m4_express
+    circfirm cache list --board-id feather_m4_express
 
     # Save a version of CircuitPython to the cache
     # (You can also use the --language option here)
@@ -65,7 +73,7 @@ The follow commands show some of the functionality of ``circfirm``:
     # Clear the cached CircuitPython versions
     circfirm cache clear
 
-    # You can use --board, --version, and --language options to further specify
+    # You can use --board-id, --version, and --language options to further specify
     # what firmwares should be cleared - this clears version 7.0.0 firmwares for
     # all boards and in all languages
     circfirm cache clear --version 7.0.0
@@ -74,3 +82,8 @@ The follow commands show some of the functionality of ``circfirm``:
     circfirm --help
     circfirm install --help
     circfirm cache save --help
+
+License
+=======
+
+This software is provided under an MIT license.