📚 Docs (#10)

* Adds auto generating docs from docstrings

* Deploy docs with reusable workflow

* Split models into own docs

* Change Pipeline.apps to AnyHttpUrl

* Move test deps into test group, made optional

* Adds poetry_args to pytest workflow

* Fix flake errors

.github/workflows/docs.yml

@@ -0,0 +1,11 @@
+name: 📖 Docs
+
+on:
+  push:
+    branches:
+      - main
+      - docs
+jobs:
+  build:
+    name: 📓 Build and deploy docs
+    uses: WGBH-MLA/.github/.github/workflows/docs.yml@main

.github/workflows/pytest.yml

@@ -8,6 +8,11 @@ on:
         default: 3.11
         type: string
 
+      poetry_args:
+        description: Additional args to pass to poetry.
+        type: string
+        default: --with test
+
       pytest_args:
         description: Additional args to pass to pytest.
         type: string
@@ -36,14 +41,14 @@ jobs:
         uses: actions/cache@v3
         with:
           path: .venv
-          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+          key: venv-test-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
 
       - name: 🏋 Download dependencies
         if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root
+        run: poetry install --no-interaction --no-root ${{ inputs.poetry_args }}
 
       - name: 🏗️ Install dependencies
-        run: poetry install --no-interaction
+        run: poetry install --no-interaction ${{ inputs.poetry_args }}
 
       - name: 🧪 Run pytest suite
         run: poetry run pytest -v --cov --cov-report lcov ${{ inputs.pytest_args }}

.gitignore

@@ -1,3 +1,7 @@
+# Coverage files
 htmlcov
 .coverage
-coverage.lcov
+coverage.lcov
+
+# Docs
+site

Dockerfile

@@ -1,12 +1,12 @@
 FROM python
+RUN pip install -U pip uvicorn
 
 WORKDIR /app
 
-COPY ./pyproject.toml .
-COPY ./README.md .
-COPY ./fastclam /app/fastclam
+COPY pyproject.toml poetry.lock README.md ./
+COPY fastclam fastclam
 
-RUN pip install . uvicorn
+RUN pip install .
 
 
 CMD [ "uvicorn", "fastclam.app:app", "--host", "0.0.0.0" ]

docs/index.md

@@ -0,0 +1,26 @@
+# FastCLAM
+
+FastAPI for CLAMS
+
+## install
+
+Clone the repository
+
+```bash
+git clone https://github.com/WGBH-MLA/FastCLAM
+cd FastCLAM/
+```
+
+### Poetry (Recommended)
+
+Install with poetry
+
+```bash
+poetry install
+```
+
+### Pip
+
+```bash
+pip3 install .
+```

docs/reference/app.md

@@ -0,0 +1,3 @@
+# App
+
+::: fastclam.app

docs/reference/index.md

@@ -0,0 +1,3 @@
+# Reference
+
+::: fastclam

docs/reference/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: fastclam.models

fastclam/__init__.py

@@ -0,0 +1,12 @@
+"""# FastCLAM
+
+FastAPI for CLAMS
+
+Example:
+    Run the server:
+        `$ uvicorn fastclam.app`
+
+    Use the API docs to make requests:
+        [localhost:8000/docs](http://localhost:8000/docs)
+
+"""

fastclam/app.py

@@ -2,30 +2,22 @@
 from fastapi.responses import PlainTextResponse
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from clams.source import generate_source_mmif
-from pydantic import BaseModel
-from typing import List
+from json import loads
 import requests
 from .log import log
+from .models import Inputs, Pipeline
 from .version import __VERSION__
 from xml.etree import ElementTree
 from xml.etree.ElementTree import ParseError
-from json import loads
 from json.decoder import JSONDecodeError
 
 
-class Inputs(BaseModel):
-    files: List[str]
-
-
-class Pipeline(Inputs):
-    apps: List[str]
-
-
 class MMIFException(HTTPException):
     pass
 
 
 app = FastAPI()
+app = FastAPI(title='FastCLAM')
 
 
 @app.exception_handler(StarletteHTTPException)
@@ -35,7 +27,7 @@ async def http_exception_handler(request, exc):
 
 @app.get('/')
 def home() -> dict:
-    """version info"""
+    """Return version info"""
     return {'FastCLAM': __VERSION__}
 
 

fastclam/models.py

@@ -0,0 +1,31 @@
+"""Models
+
+Pipeline validation models
+"""
+
+from pydantic import BaseModel, AnyHttpUrl
+from typing import List
+
+
+class Inputs(BaseModel):
+    """Inputs
+
+    Accepts list of files as input
+
+    Attributes:
+        files: A List of file paths as strings
+    """
+
+    files: List[str]
+
+
+class Pipeline(Inputs):
+    """Pipeline
+
+    A simple pieline validator, based on Inputs
+
+    Attributes:
+        apps: A List of apps to run, where each appp is a url string for the service
+    """
+
+    apps: List[AnyHttpUrl]

mkdocs.yml

@@ -0,0 +1,60 @@
+site_name: FastCLAM
+site_description: FastAPI for CLAMS
+repo_url: https://github.com/WGBH-MLA/FastCLAM
+edit_uri: ''
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - def_list
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+  - tables
+
+theme:
+  name: material
+  palette:
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        icon: material/lightbulb-outline
+        name: Switch to light mode
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        icon: material/lightbulb-on-outline
+        name: Switch to dark mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.indexes
+    - toc.integrate
+    - navigation.top
+    - content.code.annotate
+
+plugins:
+  - search
+  - mkdocstrings
+
+watch:
+  - fastclam
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/WGBH-MLA/FastCLAM
+  version:
+    provider: mike