Qualytics User Guide Repository

This repository contains the documentation for the Qualytics platform, built using Material for MkDocs.

Getting Started

Requirements

This project requires the following tools:

• Python 3.13+
• MkDocs
• pre-commit
• typos
• mkdocs-print-site-plugin
• VS Code with the Run on Save extension (recommended)

Running the Project Locally

To preview the documentation locally

1. Activate the virtual environment
2. Run the following command:

mkdocs serve

Note

By default, the documentation will be served at http://localhost:8000.

Tip

To run it on a custom port (e.g., 8080):

mkdocs serve -a localhost:8080

Enabling PDF Export

To enable PDF export via the print-site plugin:

1. Open the mkdocs.yml file.
2. Set the print-site plugin to enabled.
3. Run mkdocs build or mkdocs serve.

Setting Up the Local Environment

Create a Virtual Environment

Create a Python virtual environment:

python3 -m venv <your_env_name>

Note

Replace <your_env_name> with your desired virtual environment folder name.

Activate the Virtual Environment

Use the appropriate command based on your operating system and shell:

Platform	Shell	Command
POSIX	bash/zsh	source <venv>/bin/activate
	fish	source <venv>/bin/activate.fish
	csh/tcsh	source <venv>/bin/activate.csh
	pwsh	<venv>/bin/Activate.ps1
Windows	cmd.exe	<venv>\Scripts\activate.bat
	PowerShell	<venv>\Scripts\Activate.ps1

Note

Replace <venv> with the path to your virtual environment folder.

Upgrade pip

python -m pip install --upgrade pip

Install Project Dependencies

pip install -r requirements.txt

Pre-Commit Setup

This repository uses pre-commit to automatically check for spelling errors using typos.

Install Pre-Commit

pip install pre-commit

Install Pre-Commit Hooks

pre-commit install

Run Typos Manually

To run the pre-commit checks manually:

pre-commit run --all-files

Run on Save (Opctional)

If you are using Visual Studio Code, it's recommended to install the Run on Save extension.

With this extension, every time you save a file in the project, it automatically executes Typos to check for misspelled words throughout the codebase. The results will be shown in the Output panel under the Run On Save section.

To configure it, add the following snippet to your .vscode/settings.json:

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": ".*",
        "cmd": "pre-commit run --all-files"
      }
    ]
  }
}

Note

Make sure pre-commit is installed and the virtual environment is activated in your terminal when using this setup.