feat: readthedocs documentation

Author: DiogoRibeiro7

.github/workflows/dependabot.yml

@@ -0,0 +1,69 @@
+# Dependabot configuration file
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # Enable version updates for Python
+  - package-ecosystem: "pip"
+    # Look for requirements files in the root directory
+    directory: "/"
+    # Check for updates once a week (Monday)
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    # Group dependencies to consolidate PRs
+    groups:
+      dev-dependencies:
+        patterns:
+          - "black"
+          - "isort"
+          - "ruff"
+          - "mypy"
+          - "pytest*"
+          - "bandit"
+          - "pre-commit"
+      production-dependencies:
+        patterns:
+          - "*"
+        exclude-patterns:
+          - "black"
+          - "isort"
+          - "ruff"
+          - "mypy"
+          - "pytest*"
+          - "bandit"
+          - "pre-commit"
+    # Maximum number of open PRs
+    open-pull-requests-limit: 10
+    # Prefix PR titles
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    # Add labels to PRs
+    labels:
+      - "dependencies"
+      - "automerge"
+    # Allow automatic merging
+    reviewers:
+      - "DiogoRibeiro7"
+    assignees:
+      - "DiogoRibeiro7"
+
+  # Enable version updates for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "github_actions"
+      - "automerge"
+    reviewers:
+      - "DiogoRibeiro7"
+    assignees:
+      - "DiogoRibeiro7"

.github/workflows/docstring-coverage.yml

@@ -0,0 +1,109 @@
+name: Docstring Coverage
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+jobs:
+  docstring-coverage:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          
+      - name: Check docstring coverage
+        run: |
+          python scripts/check_docstring_coverage.py --min-coverage 80
+          
+      - name: Generate docstring coverage badge
+        run: |
+          python -c "
+          import re
+          import subprocess
+          import json
+          
+          # Run the docstring coverage script and capture output
+          result = subprocess.run(
+              ['python', 'scripts/check_docstring_coverage.py', '--dir', 'src'],
+              capture_output=True,
+              text=True
+          )
+          
+          # Extract the overall coverage percentage
+          match = re.search(r'Overall docstring coverage: (\d+\.\d+)%', result.stdout)
+          if match:
+              coverage = float(match.group(1))
+              
+              # Determine badge color
+              color = 'red'
+              if coverage >= 90:
+                  color = 'brightgreen'
+              elif coverage >= 80:
+                  color = 'green'
+              elif coverage >= 70:
+                  color = 'yellowgreen'
+              elif coverage >= 60:
+                  color = 'yellow'
+              elif coverage >= 50:
+                  color = 'orange'
+                  
+              # Create badge URL
+              badge_url = f'https://img.shields.io/badge/docstring%20coverage-{coverage:.1f}%25-{color}'
+              
+              # Update README.md
+              with open('README.md', 'r') as f:
+                  readme = f.read()
+                  
+              # Look for existing docstring coverage badge
+              docstring_badge_pattern = r'!\[Docstring Coverage\]\(https://img\.shields\.io/badge/docstring%20coverage-[\d\.]+%25-[a-z]+\)'
+              if re.search(docstring_badge_pattern, readme):
+                  # Replace existing badge
+                  readme = re.sub(docstring_badge_pattern, f'![Docstring Coverage]({badge_url})', readme)
+              else:
+                  # Look for badge section to add to
+                  badge_section = re.search(r'(!\[[^\]]+\]\([^\)]+\)[ \t]*)+', readme)
+                  if badge_section:
+                      # Add to existing badges
+                      end_pos = badge_section.end()
+                      readme = readme[:end_pos] + f' ![Docstring Coverage]({badge_url})' + readme[end_pos:]
+                  else:
+                      # Add after first line
+                      first_line_end = readme.find('\\n')
+                      if first_line_end != -1:
+                          readme = readme[:first_line_end+1] + f'\\n![Docstring Coverage]({badge_url})\\n' + readme[first_line_end+1:]
+                      else:
+                          readme = readme + f'\\n\\n![Docstring Coverage]({badge_url})\\n'
+              
+              with open('README.md', 'w') as f:
+                  f.write(readme)
+              
+              print(f'Updated README.md with docstring coverage badge: {coverage:.1f}%')
+          else:
+              print('Could not extract docstring coverage percentage')
+          "
+          
+      - name: Commit updated README with docstring coverage badge
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git diff --quiet && git diff --staged --quiet || (
+            git commit -m "docs: update docstring coverage badge [skip ci]"
+            git push
+          )
+        
+permissions:
+  contents: write

.readthedocs.yaml

@@ -0,0 +1,38 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_create_environment:
+      # Install poetry
+      - pip install poetry
+      # Tell poetry to not use a virtual environment
+      - poetry config virtualenvs.create false
+    post_install:
+      # Install dependencies with poetry
+      - poetry install --with docs
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+  - epub
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased]
 
 ### Added
+
 - Enhanced development tooling with Black, isort, Bandit, and pre-commit hooks
 - Added tox.ini for multi-environment testing
 - Added .editorconfig for consistent coding style
@@ -17,27 +18,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Improved GitHub issue and PR templates
 
 ### Changed
+
 - Updated Makefile with additional commands for development tasks
 - Enhanced pyproject.toml with more comprehensive configurations
 - Improved code quality settings with stricter linting rules
 
 ### Fixed
+
 - Fixed GitHub Actions permissions for the code coverage workflow
 
 ## [0.1.1] - 2025-08-14
 
 ### Added
+
 - Initial package structure
 - Basic hello function
 - Testing setup with pytest
 - Automated dependency management scripts
 
 ### Changed
+
 - Updated pyproject.toml to use modern Poetry configuration
 
 ## [0.1.0] - 2025-08-01
 
 ### Added
+
 - Initial release
 - Basic project structure
 - MIT License

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install format lint type-check test test-cov clean build publish-test publish setup dev-install security docs tox
+.PHONY: help install format lint type-check test test-cov clean build publish-test publish setup dev-install security docs tox docs-api docs-build docs-live
 
 help:
 	@echo "Available commands:"
@@ -12,20 +12,23 @@ help:
 	@echo "  make test-cov     Run tests with coverage"
 	@echo "  make tox          Run tests in multiple Python environments"
 	@echo "  make security     Run security checks with bandit"
-	@echo "  make docs         Generate documentation"
+	@echo "  make docs         Generate documentation with pdoc"
+	@echo "  make docs-api     Generate Sphinx API documentation"
+	@echo "  make docs-build   Build Sphinx documentation"
+	@echo "  make docs-live    Run a live server for Sphinx documentation"
 	@echo "  make clean        Remove build artifacts"
 	@echo "  make build        Build package"
 	@echo "  make publish-test Publish to TestPyPI"
 	@echo "  make publish      Publish to PyPI"
 
 install:
-	poetry install --no-dev
+	poetry install --without dev,docs
 
 dev-install:
-	poetry install
+	poetry install --with dev
 
 setup:
-	poetry install
+	poetry install --with dev
 	pre-commit install
 
 format:
@@ -54,10 +57,23 @@ security:
 docs:
 	poetry run python scripts/generate_docs.py
 
+docs-api:
+	cd docs && python make_api_docs.py
+
+docs-build:
+	poetry install --with docs
+	cd docs && $(MAKE) html
+
+docs-live:
+	poetry install --with docs
+	cd docs && $(MAKE) livehtml
+
 clean:
 	rm -rf build/
 	rm -rf dist/
 	rm -rf *.egg-info
+	rm -rf docs/_build/
+	rm -rf docs/api/
 	find . -type d -name __pycache__ -exec rm -rf {} +
 	find . -type f -name "*.pyc" -delete
 

docs/Makefile

@@ -0,0 +1,33 @@
+# 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     = .
+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 clean livehtml apidoc
+
+# Clean build files
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf api/*
+
+# Generate API documentation
+apidoc:
+	python make_api_docs.py
+
+# Build documentation with live reload
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) --open-browser
+
+# 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)