Alpha

.github/copilot-instructions.md

@@ -0,0 +1,43 @@
+# GitHub Copilot Instructions for Titli
+
+## General Guidelines
+- Prefer clear, modular Python code following PEP8 style.
+- Use type hints and docstrings for all public functions and classes.
+- When generating code, prefer using the existing `titli.fe` and `titli.ids` modules for feature extraction and IDS models, respectively.
+- For new feature extractors, subclass from the base classes in `titli.fe`.
+- For new IDS models, subclass from the base classes in `titli.ids`.
+- Use utility functions from `titli.utils` where possible.
+- When writing examples, place them in the `examples/` directory and use relative imports.
+- For tests, use clear, minimal examples and avoid duplicating logic from the main codebase.
+
+## Naming and Structure
+- Use descriptive, lowercase file and folder names with underscores (e.g., `after_image.py`).
+- Place images and documentation assets in `assets/images/`.
+- Keep all user-facing documentation in `README.md` and `INSTRUCTIONS.md`.
+
+## Documentation
+- Always update the pipeline diagram in `assets/images/` and reference it in the `README.md` when the architecture changes.
+- Add docstrings to all new classes, methods, and functions.
+- When adding new features, update `INSTRUCTIONS.md` with usage details.
+
+## Dependencies
+- Use only the dependencies listed in `pyproject.toml` and `setup.py` unless absolutely necessary.
+- For deep learning, prefer PyTorch (`torch`, `torchvision`).
+
+## Security and Data
+- Do not include sensitive data or credentials in code or documentation.
+- Use sample or dummy data in examples.
+
+## Contribution
+- Follow the structure and conventions of the existing codebase.
+- Add new scripts to `examples/` and new modules to the appropriate subpackage.
+- Update documentation and add usage examples for new features.
+
+## Copilot Behavior
+- When suggesting code, prefer using and extending the existing Titli framework rather than writing from scratch.
+- Avoid generating duplicate code; reuse and reference existing modules.
+- When in doubt, prompt the user to clarify requirements or point to relevant files.
+
+---
+
+_This file guides GitHub Copilot to generate code and documentation that is consistent with the Titli project’s architecture and standards._

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Build Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+
+    - name: Build documentation
+      run: |
+        cd docs
+        make html
+
+    - name: Check for broken links
+      run: |
+        cd docs
+        make linkcheck || true
+
+    - name: Upload documentation artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation
+        path: docs/build/html/
+        retention-days: 30

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
 
 # PyBuilder
 .pybuilder/

README.md

@@ -1,10 +1,33 @@
 # Titli
-Artificial Intelligence based Intrusion Detection Systems
+A toolkit for hosting feature extraction, model training, model inference, and model evaluation of AI-based Intrusion Detection Systems
+<p align="center">
+	<img src="assets/images/pipeline-overview.jpg" alt="Pipeline Overview" width="800" />
+</p>
 
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/titli)
 ![PyPI - Version](https://img.shields.io/pypi/v/titli)
 ![GitHub License](https://img.shields.io/github/license/spg-iitd/titli)
 
+## Documentation
+
+📚 **[Read the full documentation](docs/)** to get started with Titli.
+
+The documentation includes:
+- Installation guide
+- Quick start tutorial
+- Detailed usage examples
+- Complete API reference
+- And more!
+
+To build the documentation locally:
+```bash
+cd docs
+pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
+make html
+```
+
+Then open `docs/build/html/index.html` in your web browser.
+
 ### Installation
 ```
 pip install titli

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,144 @@
+# Titli Documentation
+
+This directory contains the Sphinx-based documentation for the Titli project.
+
+## Building the Documentation
+
+### Prerequisites
+
+Install Sphinx and required extensions:
+
+```bash
+pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
+```
+
+### Build HTML Documentation
+
+To build the HTML documentation:
+
+```bash
+cd docs
+make html
+```
+
+The generated HTML files will be in `build/html/`. Open `build/html/index.html` in a web browser to view the documentation.
+
+### Build Other Formats
+
+Sphinx supports multiple output formats:
+
+```bash
+# PDF (requires LaTeX)
+make latexpdf
+
+# EPUB
+make epub
+
+# Plain text
+make text
+
+# View all available formats
+make help
+```
+
+### Clean Build Artifacts
+
+To remove all generated files:
+
+```bash
+make clean
+```
+
+## Documentation Structure
+
+```
+docs/
+├── source/
+│   ├── conf.py              # Sphinx configuration
+│   ├── index.rst            # Main documentation page
+│   ├── installation.rst     # Installation guide
+│   ├── quickstart.rst       # Quick start guide
+│   ├── usage.rst            # Detailed usage guide
+│   ├── changelog.rst        # Version history
+│   ├── license.rst          # License information
+│   └── api/                 # API reference documentation
+│       ├── fe.rst           # Feature extractors API
+│       ├── ids.rst          # IDS models API
+│       └── utils.rst        # Utilities API
+├── build/                   # Generated documentation (not in git)
+├── Makefile                 # Unix/Linux build commands
+└── make.bat                 # Windows build commands
+```
+
+## Updating Documentation
+
+### Modifying Existing Pages
+
+Edit the `.rst` files in the `source/` directory. After making changes, rebuild the documentation:
+
+```bash
+make html
+```
+
+### Adding New Pages
+
+1. Create a new `.rst` file in `source/` or appropriate subdirectory
+2. Add the file to the `toctree` in `source/index.rst` or another appropriate parent page
+3. Rebuild the documentation
+
+### Updating API Documentation
+
+API documentation is automatically generated from docstrings in the source code. To update:
+
+1. Modify docstrings in the Python source files
+2. Rebuild the documentation
+
+## Documentation Style
+
+- Use reStructuredText (RST) format
+- Follow Google or NumPy docstring conventions
+- Include code examples where appropriate
+- Add cross-references using Sphinx roles (`:doc:`, `:ref:`, `:class:`, etc.)
+
+## Viewing Documentation Online
+
+The documentation can be hosted on:
+
+- [Read the Docs](https://readthedocs.org/)
+- GitHub Pages
+- Your own web server
+
+## Troubleshooting
+
+### Import Errors During Build
+
+If you see import errors when building:
+
+```bash
+# Install project dependencies
+pip install -e ..
+```
+
+### Missing Dependencies
+
+```bash
+# Install all documentation dependencies
+pip install -r requirements-docs.txt  # If such file exists
+# Or install individually:
+pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
+```
+
+### Warnings During Build
+
+Some warnings are expected (e.g., network timeout for intersphinx). Critical errors will stop the build.
+
+## Contributing
+
+When contributing documentation:
+
+1. Build locally and verify changes
+2. Check for broken links and references
+3. Ensure code examples are accurate and working
+4. Follow the existing documentation structure and style
+
+For more information, see the [Sphinx documentation](https://www.sphinx-doc.org/).

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,4 @@
+# Documentation dependencies for Titli
+sphinx>=8.0.0
+sphinx-rtd-theme>=3.0.0
+sphinx-autodoc-typehints>=3.0.0