Merge pull request #153 from ORNL/sphinx-docs

Sphinx documentation

.github/workflows/run-checks.yml

@@ -1,4 +1,4 @@
-name: Ruff linter and formatter checks
+name: Linter, formatter, and docs checks
 on: [pull_request]
 
 permissions:
@@ -18,13 +18,14 @@ jobs:
           python-version: "3.10"
           cache: "pip"
 
-      - name: Install Ruff
+      - name: Install package and dependencies
         run: |
           python -m pip install --upgrade pip
           python -m pip install ruff
+          python -m pip install .[docs]
 
-      - name: Run ruff linter checks
-        run: ruff check src
+      - name: Run linter and formatter checks using ruff
+        run: make checks
 
-      - name: Run ruff formatter checks
-        run: ruff format --check src
+      - name: Run HTML builder for Sphinx documentation
+        run: make docs

CONTRIBUTING.md

@@ -1,71 +1,68 @@
+# Contributing
 
-# Branches and Pull Requests
+Welcome to the FlowCept project! To make sure new contributions align well with the project, following there are some guidelines to help you create code that fits right in. Following them increases the chances of your contributions being merged smoothly.
 
-We have two protected branches: `dev` and `main`. This means that these two branches should be as stable as
-possible, especially the `main` branch. PRs to them should be peer-reviewed.   
+## Code Linting and Formatting
 
-The `main` branch always has the latest working version, with a tagged release published to 
-[pypi](https://pypi.org/project/flowcept). 
-The `dev` branch may be ahead of `main` while new features are
-being implemented. Feature branches should be pull requested to the `dev` branch. Pull requests into the 
-`main` branch should always be made from the `dev` branch and be merged when the developers agree it is time
-to do so.
+All Python code in the FlowCept package should adhere to the [PEP 8](https://peps.python.org/pep-0008/) style guide. All linting and formatting checks should be performed with [Ruff](https://github.com/astral-sh/ruff). Configuration for Ruff is defined in the [pyproject.toml](./pyproject.toml) file. The commands shown below will run the Ruff linter and formatter checks on the source directory:
 
-# CI/CD Pipeline
+```text
+ruff check src
+ruff format --check src
+```
 
-## Automated versioning
+## Documentation
 
-Flowcept ~~[attempts to]~~ follows semantic versioning.
-There is a [GitHub Action](.github/workflows/create-release-n-publish.yml) that automatically bumps the 
-patch number of the version at PRs to the main branch and uploads to the package to pypi.
+[Sphinx](https://www.sphinx-doc.org) along with the [Furo theme](https://github.com/pradyunsg/furo) are used to generate documentation for the project. The **docs** optional dependencies are needed to build the documentation on your local machine. Sphinx uses docstrings from the source code to build the API documentation. These docstrings should adhere to the [NumPy docstring conventions](https://numpydoc.readthedocs.io/en/latest/format.html). The commands shown below will build the documentation using Sphinx:
 
-## Automated Tests and Code format check
+```text
+cd docs
+make html
+```
 
-All human-triggered commits to any branch will launch the [automated tests GitHub Action](.github/workflows/run-unit-tests.yml).
-They will also trigger the [code format checks](.github/workflows/code-formatting.yml),
-using black and flake8. So, make sure you run the following code before your commits.
+## Branches and Pull Requests
 
-```shell
-$ black .
-$ flake8 .  
-```
+There are two protected branches in this project: `dev` and `main`. This means that these two branches should be as stable as possible, especially the `main` branch. PRs to them should be peer-reviewed.
 
-## Automated Releases
+The `main` branch always has the latest working version of FlowCept, with a tagged release published to [PyPI](https://pypi.org/project/flowcept).
 
-All commits to the `main` branch will launch the [automated publish and release GitHub Action](.github/workflows/create-release-n-publish.yml).
-This will create a [tagged release](https://github.com/ORNL/flowcept/releases) and publish the package to [pypi](https://pypi.org/project/flowcept).
+The `dev` branch may be ahead of `main` while new features are being implemented. Feature branches should be pull requested to the `dev` branch. Pull requests into the `main` branch should always be made from the `dev` branch and be merged when the developers agree it is time to do so.
 
-# Checklist for Creating a new FlowCept adapter
+## Issue Labels
 
-1. Create a new package directory under `flowcept/flowceptor/plugins`
-2. Create a new class that inherits from `BaseInterceptor`, and consider implementing the abstract methods:
-    - Observe
-    - Intercept
-    - Callback
-    - Prepare_task_msg
-
-See the existing plugins for a reference.
+When a new issue is created a priority label should be added indicating how important the issue is.
 
-3. [Optional] You may need extra classes, such as 
-   local state manager (we provide a generic [`Interceptor State Manager`](flowcept/flowceptor/adapters/interceptor_state_manager.py)),
-   `@dataclasses`, Data Access Objects (`DAOs`), and event handlers.
+* `priority:low` - syntactic sugar, or addressing small amounts of technical debt or non-essential features
+* `priority:medium` - is important to the completion of the milestone but does not require immediate attention
+* `priority:high` - is essential to the completion of a milestone
 
-4. Create a new entry in the [settings.yaml](resources/settings.yaml) file and in the [Settings factory](flowcept/commons/settings_factory.py)
+## CI/CD Pipeline
 
-5. Create a new `requirements.txt` file under the directory [extra_requirements](extra_requirements) and
-adjust the [setup.py](setup.py).
+### Automated versioning
 
-6. [Optional] Add a new constant to [vocabulary.py](flowcept/commons/vocabulary.py).
+FlowCept follows semantic versioning. There is a [GitHub Action](.github/workflows/create-release-n-publish.yml) that automatically bumps the patch number of the version at PRs to the main branch and uploads the package to PyPI.
 
-7. [Optional] Ajust flowcept.__init__.py.
+### Automated tests and code format check
 
+All human-triggered commits to any branch will launch the [automated tests GitHub Action](.github/workflows/run-tests.yml). PRs into `dev` or `main` will also trigger the [code linter and formatter checks](.github/workflows/run-checks.yml), using Ruff.
 
-# Issue Labels
+### Automated releases
 
-When a new issue is created a priority label should be added indicating how important the issue is.
+All commits to the `main` branch will launch the [automated publish and release GitHub Action](.github/workflows/create-release-n-publish.yml). This will create a [tagged release](https://github.com/ORNL/flowcept/releases) and publish the package to [PyPI](https://pypi.org/project/flowcept).
 
-* `priority:low` - syntactic sugar, or addressing small amounts of technical debt or non-essential features
-* `priority:medium` - is important to the completion of the milestone but does not require immediate attention
-* `priority:high` - is essential to the completion of a milestone
+## Checklist for Creating a new FlowCept adapter
 
-Reference: https://github.com/ORNL/zambeze/blob/main/CONTRIBUTING.md
+1. Create a new package directory under `flowcept/flowceptor/plugins`
+2. Create a new class that inherits from `BaseInterceptor`, and consider implementing the abstract methods:
+    - Observe
+    - Intercept
+    - Callback
+    - Prepare_task_msg
+
+See the existing plugins for a reference.
+
+3. [Optional] You may need extra classes, such as local state manager (we provide a generic [`Interceptor State Manager`](flowcept/flowceptor/adapters/interceptor_state_manager.py)), `@dataclasses`, Data Access Objects (`DAOs`), and event handlers.
+4. Create a new entry in the [settings.yaml](resources/settings.yaml) file and in the [Settings factory](flowcept/commons/settings_factory.py)
+5. Create a new entry in the [pyproject.toml](./pyproject.toml) file under the `[project.optional-dependencies]` section and adjust the rest of the file accordingly.
+6. [Optional] Add a new constant to [vocabulary.py](flowcept/commons/vocabulary.py).
+7. [Optional] Adjust flowcept.__init__.py.

Makefile

@@ -0,0 +1,38 @@
+# Show help, place this first so it runs with just `make`
+help:
+	@printf "\nCommands:\n"
+	@printf "\033[32mchecks\033[0m          run ruff linter and formatter checks\n"
+	@printf "\033[32mclean\033[0m           remove cache directories and Sphinx build output\n"
+	@printf "\033[32mdocs\033[0m            build HTML documentation using Sphinx\n"
+	@printf "\033[32mservices\033[0m        run services using Docker\n"
+	@printf "\033[32mservices-stop\033[0m   stop the running Docker services\n"
+	@printf "\033[32mtests\033[0m           run unit tests with pytest\n"
+
+
+# Run linter and formatter checks using ruff
+checks:
+	ruff check src
+	ruff format --check src
+
+# Remove cache directories and Sphinx build output
+clean:
+	rm -rf .ruff_cache
+	rm -rf .pytest_cache
+	sphinx-build -M clean docs docs/_build
+
+# Build the HTML documentation using Sphinx
+.PHONY: docs
+docs:
+	sphinx-build -M html docs docs/_build
+
+# Run services using Docker
+services:
+	docker compose --file deployment/compose.yml up --detach
+
+# Stop the running Docker services and remove volumes attached to containers
+services-stop:
+	docker compose --file deployment/compose.yml down --volumes
+
+# Run unit tests using pytest
+tests:
+	pytest --ignore=tests/decorator_tests/ml_tests/llm_tests