Merge pull request #5 from mbsantiago/dev

Fix authentication issue raised at #4.

Author: mbsantiago

.gitignore

@@ -166,12 +166,11 @@ front/src/old_hooks
 old
 
 site
+back/user_guide
 
 whombat.db
 .pdm-python
-back/src/whombat/statics
-back/src/whombat/statics
+back/src/whombat/statics/*
+back/src/whombat/user_guide/*
 back/.build_venv
-back/user_guide
-back/src/whombat/user_guide
-.bumpversion.cfg
+.bumpversion.cfg

Dockerfile

@@ -59,6 +59,7 @@ COPY back/app.py /code/app.py
 COPY back/pyproject.toml /code/pyproject.toml
 COPY back/alembic.ini /code/alembic.ini
 COPY back/README.md /code/README.md
+COPY back/LICENSE /code/LICENSE
 
 # Install Whombat
 RUN pip install --no-deps .

Makefile

@@ -11,3 +11,6 @@ build-guide:
 
 bundle-pyinstaller:
 	bash scripts/bundle_linux.sh
+
+publish:
+	bash scripts/publish_pypi.sh

README.md

@@ -1,5 +1,14 @@
 # Whombat
 
+![GitHub License](https://img.shields.io/github/license/mbsantiago/whombat)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmbsantiago%2Fwhombat%2Fdev%2Fback%2Fpyproject.toml)
+![Static Badge](https://img.shields.io/badge/formatting-black-black)
+[![codecov](https://codecov.io/gh/mbsantiago/whombat/graph/badge.svg?token=WMzUfSXIyL)](https://codecov.io/gh/mbsantiago/whombat)
+![build](https://github.com/mbsantiago/whombat/actions/workflows/bundle.yml/badge.svg)
+![lint](https://github.com/mbsantiago/whombat/actions/workflows/lint.yml/badge.svg)
+![docs](https://github.com/mbsantiago/whombat/actions/workflows/docs.yml/badge.svg)
+![tests](https://github.com/mbsantiago/whombat/actions/workflows/test.yml/badge.svg)
+
 **Whombat** is an open-source, web-based audio annotation tool designed to streamline audio data labeling and annotation, with a particular focus on supporting machine learning model development.
 
 ## Installation

back/Makefile

@@ -27,10 +27,10 @@ export PRINT_HELP_PYSCRIPT
 
 BROWSER := python -c "$$BROWSER_PYSCRIPT"
 
-help:
+help:  ## show this help message and exit
 	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 
-clean: clean-build clean-pyc clean-test clean-docs
+clean: clean-build clean-pyc clean-test clean-docs  ## remove all build, test, coverage and Python artifacts
 
 clean-build:
 	rm -fr build/
@@ -73,35 +73,35 @@ lint/pyright:
 
 lint: lint/flake8 lint/black lint/pycodestyle lint/pydocstyle lint/pylint lint/pyright ## check style
 
-format:
+format:  ## format code
 	isort src tests
 	black src tests
 
-test:
+test:  ## Run all tests
 	pytest -n auto
 
-install: clean
+install: clean  ## install the package to the active Python's site-packages
 	pip install .
 
-coverage:
+coverage:  ## check code coverage
 	coverage run --source whombat -m pytest
 	coverage report -m
 	coverage html
 	$(BROWSER) htmlcov/index.html
 
-build-docs:
+build-docs:  ## build documentation
 	mkdocs build
 
-build-guide:
+build-guide:  ## build user guide
 	mkdocs build -f mkdocs-guide.yml -d src/whombat/user_guide
 
-serve-docs:
+serve-docs:  ## serve documentation
 	URL="http://localhost:8000/whombat/"; xdg-open $$URL || sensible-browser $$URL || x-www-browser $$URL || gnome-open $$URL
 	@$(ENV_PREFIX)mkdocs serve
 
-serve-guide:
+serve-guide:  ## serve user guide
 	URL="http://localhost:8000/whombat/"; xdg-open $$URL || sensible-browser $$URL || x-www-browser $$URL || gnome-open $$URL
 	@$(ENV_PREFIX)mkdocs serve -f mkdocs-guide.yml
 
-serve-dev:
+serve-dev:  ## serve development backend
 	WHOMBAT_DEV=true python -m whombat

back/README.md

@@ -1,36 +1,84 @@
-# Whombat
+# Whombat - Python Backend
 
-> [!TIP]
-> Read the latest [documentation](https://mbsantiago.github.io/whombat/)
+**whombat** is an open-source web-based audio annotation tool designed to
+facilitate audio data labeling and annotation, with a special focus on aiding
+machine learning model development.
 
-> [!IMPORTANT]
-> Whombat is in beta mode. Most features are implemented but probably buggy.
-> Expect many changes before a first release.
+For additional details on installing the entire application and its usage, refer
+to the main [README](https://github.com/mbsantiago/whombat).
 
-**whombat** is an open-source web-based audio annotation tool designed to facilitate
-audio data labeling and annotation, with a special focus on aiding machine
-learning model development.
+For the latest updates and detailed documentation, check out the official
+[documentation](https://mbsantiago.github.io/whombat/).
 
 ## Installation
 
-To use whombat, follow these steps:
+### With Pip
+
+The most straightforward method to set up the backend and Whombat Python API is
+using pip. Execute the following command:
+
+```bash
+pip install whombat
+```
+
+### From Source Code
 
 Clone the repository:
 
-```shell
+```bash
 git clone https://github.com/mbsantiago/whombat.git
 ```
 
-Install the required dependencies:
+Install the package:
 
-```shell
-bash scripts/install.sh
+```bash
+cd whombat/backend
+pip install .
 ```
 
-Run the application:
+### With Docker
 
-```shell
-bash scripts/run.sh
+Run Whombat inside a Docker container. Build the container by cloning the repository and executing:
+
+
+```bash
+git clone https://github.com/mbsantiago/whombat.git
+docker build -t whombat .
 ```
 
-Access whombat in your web browser at <http://localhost:5000>.
+Once the build is complete, run the container with:
+
+```bash
+docker run -p 5000:5000 whombat
+```
+
+### Development Environment
+
+We manage Whombat's development with `pdm`. 
+
+1. Follow the official [installation instructions](https://pdm-project.org/latest/#installation) to get `pdm` on your machine.
+
+2. Clone the repository:
+
+```bash
+git clone https://github.com/mbsantiago/whombat.git
+```
+
+3. Navigate to the backend directory and install dependencies:
+
+```bash
+cd whombat/back
+pdm install --dev
+```
+
+4. Start the development server:
+
+```bash
+pdm run make serve-dev
+```
+
+or
+
+```bash
+WHOMBAT_DEV=true pdm run python -m whombat
+```

back/docs/developer_guide/cli.md

@@ -1,5 +1,29 @@
 # Developer Guide
 
-Thank you for your patience as we craft this documentation! We're diligently
-working to provide you with valuable insights and instructions. Stay tuned for
-updates!
+Welcome to the Whombat Developer Guide. This comprehensive resource covers a
+variety of topics essential for developers:
+
+1. [Quickstart](quickstart.md): Learn how to set up a development environment on
+   your machine quickly.
+2. [Architecture](architecture.md): Gain insight into the high-level structure
+   of Whombat, its main components, and how they come together to form the final
+   application.
+3. [Database Layer](database.md): Explore information about the data stored by
+   Whombat, its storage configuration, and ways to tailor it to meet specific
+   requirements.
+4. [Python API](api.md): Discover the convenient Python API provided by Whombat
+   for interacting with stored data. Use this API to integrate Whombat's outputs
+   into your Python scripts or create custom annotation workflows.
+5. [HTTP REST API](rest_api.md): Explore the HTTP REST API that all Whombat
+   instances provide. This allows third parties to safely interact with Whombat
+   data, enabling the development of alternative frontends or other web
+   applications for working with annotation data.
+6. [Front End](front_end.md): Delve into the details of how the Whombat frontend
+   is constructed.
+7. [Plugins](plugins.md): Stay tuned for updates on the integration of a plugin
+   system, offering an easy way to incorporate third-party code into Whombat.
+   Check here for the latest information.
+8. [Contributing](../CONTRIBUTING.md): Find instructions on how to contribute to
+   this project and become part of the Whombat community.
+9. [Code of Conduct](../CODE_OF_CONDUCT.md): Familiarize yourself with our code
+   of conduct to maintain a friendly and collaborative environment.

back/docs/developer_guide/design_principles.md

@@ -1 +1,95 @@
 # Quickstart
+
+## Pre-requisites
+
+Before setting up your Whombat development environment, ensure you have the
+following tools installed:
+
+1. **Python 3.11**: We developed Whombat using this version, but any newer
+   version should be compatible. Download Python 3.11
+   [here](https://www.python.org/downloads/release/python-3117/).
+
+2. **PDM**: PDM is a Python package dependency manager that we use to manage
+   dependencies for the Python part of Whombat. Download PDM
+   [here](https://pdm-project.org/latest/#installation).
+
+3. **Node.js**: We use Node.js to develop and bundle the final JavaScript code
+   for the Whombat frontend. Download the latest version
+   [here](https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz).
+
+## Set Up a Development Environment
+
+After confirming that you have all the prerequisites ready, follow these steps
+to set up a development environment on your machine.
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/mbsantiago/whombat.git
+```
+
+2. Navigate to the backend directory and install dependencies:
+
+```bash
+cd whombat/back
+pdm install --dev
+```
+
+3. Move to the frontend directory and install all dependencies:
+
+```bash
+cd ../front
+npm install
+```
+
+These instructions ensure you have the necessary tools and dependencies to
+kickstart Whombat development on your local machine.
+
+## Running the Development Server
+
+Once installed, you can start the backend server by navigating to the `back`
+directory and running:
+
+```bash
+pdm run make serve-dev
+```
+
+You can also start the frontend development server by navigating to the `front`
+directory and running:
+
+```bash
+npm run dev
+```
+
+These commands initiate the development servers for both the backend and
+frontend components of Whombat. Navigate to [localhost:3000](localhost:3000) to
+access the development front end.
+
+## Our Standards
+
+At Whombat, we emphasize code quality and employ various tools to streamline
+development.
+
+### Code Formatting
+
+We follow the black style for Python to maintain consistent formatting
+throughout the project. Additionally, we use isort to organize imports neatly.
+For the Typescript project, prettier serves as the primary code formatter.
+
+### Linting
+
+We utilize the following tools for linting and error checking:
+
+1. Python:
+       - **Ruff** for fast overall error checking
+       - **Pyright** for type checking
+
+2. Typescript:
+       - **Eslint** for linting
+       - **Tsc** for checking Typescript code
+
+### Documentation
+
+We adhere to the Numpy docstring format for documenting Python code. Our
+documentation is built using mkdocs, providing a clear and organized structure
+for users and contributors.

back/docs/developer_guide/index.md

@@ -14,11 +14,9 @@ nav:
       - developer_guide/index.md
       - Quickstart: developer_guide/quickstart.md
       - Architecture: developer_guide/architecture.md
-      - Design Principles: developer_guide/design_principles.md
       - Database Layer: developer_guide/database.md
       - Python API: developer_guide/api.md
       - HTTP REST API: developer_guide/rest_api.md
-      - Command Line Interface: developer_guide/cli.md
       - Front End: developer_guide/front_end.md
       - Plugins: developer_guide/plugins.md
       - Contributing: CONTRIBUTING.md