Add documentation for the project

Author: befeleme

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocstrings[python] pymdown-extensions
+
+      - name: Build documentation (PR test)
+        if: github.event_name == 'pull_request'
+        run: |
+          mkdocs build --clean --strict --verbose
+          echo "📚 Documentation build successful for PR!"
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '📚 Documentation build **successful**! ✅\n\n' +
+                    '🔍 Changes validated:\n' +
+                    '- MkDocs build completed without errors\n' +
+                    '- All links and references checked\n' +
+                    '- ReadTheDocs theme applied\n\n' +
+                    '💡 Ready to merge for deployment!'
+            })
+
+      - name: Configure Git for deployment
+        if: github.ref == 'refs/heads/main'
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        run: |
+          mkdocs gh-deploy --force

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# 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 you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the docs/ directory with MkDocs
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs 

docs/changelog.md

@@ -0,0 +1,9 @@
+# Changelog
+
+For the complete and up-to-date changelog, see the [CHANGELOG.md](https://github.com/befeleme/pyp2spec/blob/main/CHANGELOG.md) file in the project root.
+
+## Links
+
+- [Full Changelog](https://github.com/befeleme/pyp2spec/blob/main/CHANGELOG.md)
+- [GitHub Releases](https://github.com/befeleme/pyp2spec/releases)
+- [PyPI Package](https://pypi.org/project/pyp2spec/)

docs/contributing/development-setup.md

@@ -0,0 +1,98 @@
+# Development Setup
+
+This guide helps you set up a development environment for contributing to pyp2spec.
+
+## Prerequisites
+
+- Python 3.9 or higher
+- Git
+- Linux environment (preferably Fedora)
+
+## Setting Up the Development Environment
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/befeleme/pyp2spec.git
+cd pyp2spec
+```
+
+### 2. Create a Virtual Environment
+
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### 4. Install Development Dependencies
+
+```bash
+pip install -e ".[test,docs]"
+```
+
+## Running Tests
+
+Use tox to run the test suite:
+
+```bash
+tox
+```
+
+Or run tests directly with pytest:
+
+```bash
+pytest
+```
+
+## Code Style
+
+The project uses ruff for linting. Run it with:
+
+```bash
+ruff check pyp2spec/
+```
+
+## Documentation
+
+### Building Documentation
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+The documentation will be available at `http://localhost:8000`.
+
+### Making Documentation Changes
+
+1. Edit files in the `docs/` directory
+2. Preview changes with `mkdocs serve`
+3. Build the final documentation with `mkdocs build`
+
+## Making Changes
+
+1. Create a new branch for your feature or fix
+2. Make your changes
+3. Add tests for new functionality
+4. Update documentation if needed
+5. Run tests to ensure everything works
+6. Submit a pull request
+
+## Debugging
+
+To debug pyp2spec during development:
+
+```bash
+python -m pyp2spec.pyp2spec package-name
+
+# Or run individual components
+python -m pyp2spec.pyp2conf package-name
+python -m pyp2spec.conf2spec package-name.conf
+```

docs/docs-readme.md

@@ -0,0 +1,44 @@
+# Documentation
+
+This documentation is built with [MkDocs](https://www.mkdocs.org/) using the ReadTheDocs theme.
+
+## ReadTheDocs Deployment
+
+The documentation is automatically deployed to ReadTheDocs when changes are pushed to the main branch.
+
+### Setup
+
+1. **Import your repository** to [ReadTheDocs](https://readthedocs.org/):
+   - Sign in to ReadTheDocs with your GitHub account
+   - Click "Import a Project"
+   - Select your `pyp2spec` repository
+
+2. **Configure the project**:
+   - The `.readthedocs.yaml` configuration file will be automatically detected
+   - Python version is set to 3.13
+   - Documentation dependencies are installed from the `docs` extra in `pyproject.toml`
+
+3. **Documentation URL**: https://pyp2spec.readthedocs.io/
+
+### Local Development
+
+To build and serve the documentation locally:
+
+```bash
+# Install documentation dependencies
+pip install -e .[docs]
+
+# Serve the documentation locally
+mkdocs serve
+
+# Build the documentation
+mkdocs build
+```
+
+The documentation will be available at http://127.0.0.1:8000/
+
+### Configuration Files
+
+- `.readthedocs.yaml`: ReadTheDocs configuration
+- `mkdocs.yml`: MkDocs configuration
+- `pyproject.toml`: Python project configuration with documentation dependencies

docs/examples/automode.md

@@ -0,0 +1,29 @@
+# Automode
+
+Automode is designed for automated environments where you need packages that build successfully without manual intervention (like Copr).
+It applies convenient defaults that increase the chances of creating a buildable package.
+Automode applies sensible defaults for fields that couldn't be automatically determined.
+
+## Notable features
+Import checks are limited to top-level modules only, reducing the chance of import failures due to missing system dependencies.
+
+### License handling
+
+- All found license names are validated as SPDX identifiers
+- Compliance with Fedora Legal data is checked
+- Warnings are issued for incorrect licenses but don't prevent spec generation
+- Valid SPDX expressions are automatically combined with "AND" operator
+
+## Enabling automode
+
+Use the `--automode` or `-a` flag:
+
+```bash
+pyp2spec --automode package-name
+pyp2spec -a package-name
+```
+
+## Limitations
+
+!!! warning "Not for production"
+    Packages generated with automode may not fully comply with Fedora packaging guidelines and should not be submitted for official review without manual review and adjustment.