docs: add mkdocs documentation

.github/workflows/update-documentation.yml

@@ -0,0 +1,29 @@
+name: Update Documentation
+on:
+  workflow_dispatch:
+    inputs:
+      build_tag:
+        description: "Repository tag"
+        type: string
+        required: true
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: "${{ github.event.inputs.build_tag }}"
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.10
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs mkdocs-material mkdocstrings[python] mike
+      - run: mike deploy --push --update-aliases ${{ github.event.inputs.build_tag }} latest -f

.gitignore

@@ -8,3 +8,4 @@ jmenu.spec
 .ruff_cache
 *.egg-info
 .pytest_cache
+site

README.md

@@ -1,25 +1,41 @@
 # jmenu
 
-## About
+Command line tool for fetching University of Oulu restaurant menus from the [Jamix API.](https://fi.jamix.cloud/apps/menuservice/rest)
 
-Python app to fetch University of Oulu restaurant menus from Jamix API.
-
-Versions 1.3 and above use the [Jamix API.](https://fi.jamix.cloud/apps/menuservice/rest)
-
-Versions below 1.3 work by rendering the pages with selenium, then scraping the HTML with BeautifulSoup4.
+Doubles as a general library for fetching menu info from Jamix.
 
 ## Installing
 
-Jmenu is available for install on the [Python package index.](https://pypi.org/project/jmenu/)
+### Python Package Index
 
-Install it with pip:
+jmenu is available for install on the [python package index.](https://pypi.org/project/jmenu/)
 
 ```shell
 pip install jmenu
 ```
 
+### Building from source
+
+For testing purposes, the package can be built from the repository source code.
+
+```shell
+pip install build
+python3 -m build
+pip install dist/<package_name>.whl
+```
+
 ## Usage
 
+### Command line tool
+
+jmenu can be invoked from the command line as is:
+
+```shell
+jmenu [-h] [-v] [-e] [-t] [-a markers [G, VEG ...]]
+```
+
+All flags and parameters described below
+
 | Argument        | Example | Description                             |
 | :-------------- | :------ | :-------------------------------------- |
 | -a, --allergens | g veg   | Highlights appropriately marked results |
@@ -31,8 +47,24 @@ pip install jmenu
 | -e, --explain  | Display allergen marker information |
 | -t, --tomorrow | Fetch menu results for tomorrow     |
 
+### Python library
+
+jmenu can also be imported as a library:
+
+```python
+from jmenu import main
+
+main.run()
+```
+
+Documentation for the library can be found in the [project pages.](https://jkerola.github.io/jmenu)
+
 ## Contributing
 
+Pull requests are welcome. We use [pre-commit hooks](https://pre-commit.com/) and GitHub actions to ensure code quality.
+
+### Development environment setup
+
 **Requirements**
 
 - Python 3.7+
@@ -46,15 +78,33 @@ source env/bin/activate
 pip install -r requirements.txt
 ```
 
-Test and run the tool with
+### Testing
+
+Run the tool
 
 ```shell
 python3 -m src.jmenu.main
 ```
 
-Build and install the package with
+Execute unit tests
 
+```shell
+pytest
 ```
-python3 -m build
-pip install dist/<package_name>.whl
+
+# Documentation
+
+Documentation for the project is available in the [project pages.](https://jkerola.github.io/jmenu)
+
+## Build documentation from source
+
+The documentation for the modules is built with [Mkdocs.](https://mkdocs.org) and the mkdocstrings extension, using google style docstrings.
+
+You can build it from source by installing mkdocs
+
+```shell
+pip install mkdocs mkdocs-material
+mkdocs serve
 ```
+
+and navigating to [localhost:8000](http://localhost:8000) in your browser.

docs/changelog.md

@@ -0,0 +1,7 @@
+---
+search:
+  exclude: true
+---
+--8<--
+CHANGELOG.md
+--8<--

docs/index.md

@@ -0,0 +1,2 @@
+--8<--
+README.md

docs/modules/api.md

@@ -0,0 +1 @@
+::: src.jmenu.api

docs/modules/classes.md

@@ -0,0 +1 @@
+::: src.jmenu.classes

docs/modules/main.md

@@ -0,0 +1 @@
+::: src.jmenu.main

mkdocs.yml

@@ -0,0 +1,32 @@
+site_name: jmenu
+site_author: jkerola
+repo_url: https://github.com/jkerola/jmenu
+repo_name: jkerola/jmenu
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstrings_style: numpy
+nav:
+  - Home: index.md
+  - Modules:
+      - jmenu.api: modules/api.md
+      - jmenu.classes: modules/classes.md
+      - jmenu.main: modules/main.md
+  - Changelog: changelog.md
+theme:
+  name: material
+  locale: en
+  features:
+    - toc.integrate
+    - toc.follow
+    - navigation.footer
+markdown_extensions:
+  - pymdownx.snippets
+  - pymdownx.highlight
+  - pymdownx.superfences
+extras:
+  version:
+    provider: mike

pyproject.toml

@@ -24,7 +24,7 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [project.scripts]
-jmenu = "jmenu.main:main"
+jmenu = "jmenu.main:run"
 
 [tool.pytest.ini_options]
 pythonpath = [

src/jmenu/__init__.py

@@ -0,0 +1,33 @@
+"""
+jmenu is a tool and python library for fetching University of Oulu restaurant menus from
+the Jamix API.
+
+jmenu can be invoked from the command line as is:
+
+```shell
+jmenu
+```
+
+Additional flags and parameters described below
+
+| Argument        | Example | Description                             |
+| :-------------- | :------ | :-------------------------------------- |
+| -a, --allergens | g veg   | Highlights appropriately marked results |
+
+| Flag           | Description                         |
+| :------------- | :---------------------------------- |
+| -h, --help     | Display usage information           |
+| -v, --version  | Display version information         |
+| -e, --explain  | Display allergen marker information |
+| -t, --tomorrow | Fetch menu results for tomorrow     |
+
+jmenu can also be imported as a library:
+
+```python
+from jmenu.main import main
+
+main()
+```
+
+Documentation for the library can be found at [link here]()
+"""

src/jmenu/__main__.py

@@ -1,4 +1,5 @@
-from .main import main
+from .main import run
+import sys
 
 if __name__ == "__main__":
-    main()
+    sys.exit(run())

src/jmenu/api.py

@@ -1,10 +1,9 @@
-"""api.py
-
+"""
 Contains functions used to wrangle the JAMIX API.
 This file can be imported and exposes the following functions:
 
     * fetch_restaurant
-    * parse_items_from_response
+    * parse_items
     * get_menu_items
 
 The following constants are also exposed:
@@ -23,17 +22,15 @@
 def fetch_restaurant(rest: Restaurant, fetch_date: datetime) -> list[dict]:
     """Return the JSON response containing all menu information for [Restaurant]
 
-    Parameters
-    ----------
-    rest : Restaurant
-        dataclass containing relevant restaurant information, see classes.RESTAURANTS
-    fetch_date : datetime
-        datetime object used to fetch the date specified menu
-
-    Returns
-    -------
-    list[dict]
-        parsed response json
+    Parameters:
+        rest (Restaurant):
+            dataclass containing relevant restaurant information
+        fetch_date (datetime):
+            datetime object used to fetch the date specified menu
+
+    Returns:
+        (list[dict]):
+            parsed response content
     """
     response = requests.get(
         f"{API_URL}/{rest.client_id}/{rest.kitchen_id}?lang=fi&date={fetch_date.strftime('%Y%m%d')}",
@@ -45,40 +42,35 @@ def fetch_restaurant(rest: Restaurant, fetch_date: datetime) -> list[dict]:
 def get_menu_items(rest: Restaurant, fetch_date: datetime) -> list[MenuItem]:
     """Returns a list of restaurant [MenuItems]
 
-    Parameters
-    ----------
-    rest : Restaurant
-        dataclass containing relevant restaurant information, see classes.RESTAURANTS
-    fetch_date : datetime
-        datetime object used to fetch the date specified menu
-
-    Returns
-    -------
-    list[MenuItem]
-        list of restaurant menu items, see classes.MenuItem
+    Parameters:
+        rest (Restaurant):
+            dataclass containing relevant restaurant information
+        fetch_date (datetime):
+            datetime object used to fetch the date specified menu
+
+    Returns:
+        (list[MenuItem]):
+            list of restaurant menu items, see classes.MenuItem
     """
     data = fetch_restaurant(rest, fetch_date)
-    items = parse_items_from_response(data, rest.relevant_menus)
+    items = parse_items(data, rest.relevant_menus)
     return items
 
 
-def parse_items_from_response(
-    data: list[dict], relevant_menus: list[str] = []
-) -> list[MenuItem]:
+def parse_items(data: list[dict], relevant_menus: list[str] = []) -> list[MenuItem]:
     """Returns a list of [MenuItems] parsed from JSON data
 
-    Parameters
-    ----------
-    data : list[dict]
-        parsed JSON response from the jamix API, see api._fetch_restaurant
-    relevant_menus : list[str]
-        list of menu names to consider when parsing
-        defaults to empty list
-
-    Returns
-    -------
-    list[MenuItem]
-        list of restaurant menu items, see classes.MenuItem"""
+    Parameters:
+        data (list[dict]):
+            parsed JSON response from the jamix API, see api._fetch_restaurant
+        relevant_menus (list[str]):
+            list of menu names to filter when parsing
+            defaults to all menus
+
+    Returns:
+        (list[MenuItem]):
+            list of restaurant menu items
+    """
     menus = []
     for kitchen in data:
         for m_type in kitchen["menuTypes"]: