Refactor doc structure

doc/requirements.txt

@@ -10,4 +10,5 @@ sphinxcontrib-makedomain
 sphinxcontrib-spelling
 sphinx-issues
 sphinx-argparse
+sphinx-design
 

doc/source/ai-integration/mcp-server.rst

@@ -0,0 +1,100 @@
+##########
+MCP Server
+##########
+
+The PyUCIS MCP server lets AI assistants (such as Claude) query your coverage
+databases using natural language. Instead of memorizing command syntax, you
+can ask questions like:
+
+* *"What is the overall coverage of my regression?"*
+* *"Which covergroups have the lowest coverage?"*
+* *"Show me all bins that were never hit."*
+* *"Compare today's run to yesterday's baseline and report any regressions."*
+* *"Export coverage as LCOV and tell me what genhtml command to run."*
+
+The server uses the `Model Context Protocol (MCP) <https://modelcontextprotocol.io/>`_,
+a standard interface for connecting AI tools to external data sources.
+
+Installation
+============
+
+.. code-block:: bash
+
+    pip install pyucis[dev]
+
+This installs the ``pyucis-mcp-server`` command and its dependencies.
+
+Configuring Claude Desktop
+==========================
+
+1. Find your Claude Desktop config file:
+
+   * **macOS**: ``~/Library/Application Support/Claude/claude_desktop_config.json``
+   * **Linux**: ``~/.config/Claude/claude_desktop_config.json``
+   * **Windows**: ``%APPDATA%\Claude\claude_desktop_config.json``
+
+2. Add the PyUCIS server entry:
+
+   .. code-block:: json
+
+       {
+         "mcpServers": {
+           "pyucis": {
+             "command": "pyucis-mcp-server"
+           }
+         }
+       }
+
+3. Restart Claude Desktop.
+
+The PyUCIS tools are now available in your conversations.
+
+Example Session
+===============
+
+Once connected, open a coverage database by telling Claude the file path, then ask
+questions in plain English:
+
+.. code-block:: text
+
+    You: Open /path/to/regression.xml and give me a coverage summary.
+
+    Claude: The database has 78.4% overall coverage across 142 covergroups.
+            Functional coverage is 81.2%; code coverage is 74.6%.
+            There are 23 covergroups below 50%.
+
+    You: Which covergroups have zero coverage?
+
+    Claude: The following 8 covergroups have 0% coverage: ...
+
+    You: Compare this to /path/to/baseline.xml and report regressions.
+
+    Claude: Compared to baseline, 3 items regressed: ...
+
+Available Operations
+====================
+
+The MCP server provides tools for:
+
+* Opening, listing, and closing databases
+* Coverage summary, gaps, and metrics
+* Covergroup, coverpoint, and bin details
+* Design hierarchy navigation
+* Test execution history
+* Database comparison (regression detection)
+* Hotspot analysis
+* Code coverage export (LCOV, Cobertura, JaCoCo, Clover)
+* Assertion and toggle coverage
+
+Starting the Server Manually
+============================
+
+The server communicates via stdin/stdout and is normally started by the MCP
+client automatically. To start it manually for testing:
+
+.. code-block:: bash
+
+    pyucis-mcp-server
+
+See the `MCP specification <https://modelcontextprotocol.io/>`_ for client
+integration details beyond Claude Desktop.

doc/source/cicd/github-actions.rst

@@ -0,0 +1,84 @@
+##############
+GitHub Actions
+##############
+
+The examples below show a complete coverage workflow for GitHub Actions: run tests,
+merge coverage, export to Codecov, publish an HTML report artifact, and gate the
+build on a minimum coverage threshold.
+
+Full Workflow Example
+=====================
+
+.. code-block:: yaml
+
+    name: Coverage
+
+    on:
+      push:
+        branches: [main]
+      pull_request:
+
+    jobs:
+      coverage:
+        runs-on: ubuntu-latest
+
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-python@v5
+            with:
+              python-version: "3.11"
+
+          - name: Install PyUCIS
+            run: pip install pyucis
+
+          - name: Run tests
+            run: make run_all_tests   # produces test_*.xml or test_*.dat
+
+          - name: Merge coverage
+            run: ucis merge -o merged.xml test_*.xml
+
+          - name: Check coverage threshold
+            run: |
+              COV=$(ucis show summary merged.xml -of json | jq -r '.overall_coverage')
+              echo "Coverage: ${COV}%"
+              python -c "import sys; sys.exit(0 if float('$COV') >= 80 else 1)" \
+                || (echo "Coverage below 80%" && exit 1)
+
+          - name: Export LCOV for Codecov
+            run: ucis show code-coverage merged.xml --output-format lcov > coverage.info
+
+          - name: Upload to Codecov
+            uses: codecov/codecov-action@v4
+            with:
+              files: ./coverage.info
+
+          - name: Generate HTML report
+            run: ucis report merged.xml -of html -o coverage_report.html
+
+          - name: Upload HTML report artifact
+            uses: actions/upload-artifact@v4
+            with:
+              name: coverage-report
+              path: coverage_report.html
+
+Verilator Projects
+==================
+
+Replace the merge step if your tests produce ``.dat`` files:
+
+.. code-block:: yaml
+
+    - name: Merge Verilator coverage
+      run: ucis merge --input-format vltcov -o merged.xml tests/*/coverage.dat
+
+Cobertura Upload
+================
+
+If you prefer Cobertura (e.g. for GitHub code coverage annotations via a
+third-party action):
+
+.. code-block:: yaml
+
+    - name: Export Cobertura
+      run: ucis show code-coverage merged.xml --output-format cobertura > coverage.xml

doc/source/cicd/gitlab-ci.rst

@@ -0,0 +1,63 @@
+##########
+GitLab CI
+##########
+
+The example below shows a complete coverage workflow for GitLab CI: merge
+coverage, export Cobertura for the GitLab coverage visualization, and publish
+an HTML report as a job artifact.
+
+Full Workflow Example
+=====================
+
+.. code-block:: yaml
+
+    stages:
+      - test
+      - coverage
+
+    run_tests:
+      stage: test
+      script:
+        - make run_all_tests   # produces test_*.xml
+      artifacts:
+        paths:
+          - test_*.xml
+
+    coverage:
+      stage: coverage
+      script:
+        - pip install pyucis
+
+        # Merge
+        - ucis merge -o merged.xml test_*.xml
+
+        # Coverage gate
+        - |
+          COV=$(ucis show summary merged.xml -of json | jq -r '.overall_coverage')
+          echo "Coverage: ${COV}%"
+          python3 -c "import sys; sys.exit(0 if float('$COV') >= 80 else 1)" \
+            || (echo "Coverage below 80%" && exit 1)
+
+        # Export Cobertura for GitLab coverage widget
+        - ucis show code-coverage merged.xml --output-format cobertura > coverage.xml
+
+        # Generate shareable HTML report
+        - ucis report merged.xml -of html -o coverage_report.html
+
+      coverage: '/Coverage:\s+(\d+\.\d+)%/'
+
+      artifacts:
+        reports:
+          coverage_report:
+            coverage_format: cobertura
+            path: coverage.xml
+        paths:
+          - coverage_report.html
+        expire_in: 1 week
+
+Verilator Projects
+==================
+
+.. code-block:: yaml
+
+    - ucis merge --input-format vltcov -o merged.xml tests/*/coverage.dat

doc/source/cicd/index.rst

@@ -0,0 +1,20 @@
+################
+CI/CD Integration
+################
+
+PyUCIS integrates cleanly into continuous integration pipelines. The typical
+pattern is:
+
+1. Run tests — each test produces a coverage file
+2. Merge coverage files into a single database
+3. Export to the format your CI tool expects
+4. Optionally gate the build on a coverage threshold
+
+.. toctree::
+   :maxdepth: 1
+
+   github-actions
+   gitlab-ci
+   jenkins
+
+For the available export formats see :doc:`../reporting/exporting`.

doc/source/cicd/jenkins.rst

@@ -0,0 +1,89 @@
+#######
+Jenkins
+#######
+
+The declarative pipeline below merges coverage, publishes a Cobertura report
+via the Jenkins Cobertura plugin, and generates an HTML report artifact.
+
+Prerequisites
+=============
+
+Install the `Cobertura Plugin <https://plugins.jenkins.io/cobertura/>`_
+(or `JaCoCo Plugin <https://plugins.jenkins.io/jacoco/>`_) in Jenkins.
+
+Full Pipeline Example
+=====================
+
+.. code-block:: groovy
+
+    pipeline {
+        agent any
+
+        stages {
+            stage('Test') {
+                steps {
+                    sh 'make run_all_tests'  // produces test_*.xml
+                }
+            }
+
+            stage('Coverage') {
+                steps {
+                    sh 'pip install pyucis'
+
+                    // Merge all test coverage files
+                    sh 'ucis merge -o merged.xml test_*.xml'
+
+                    // Coverage gate
+                    sh '''
+                        COV=$(ucis show summary merged.xml -of json | jq -r '.overall_coverage')
+                        echo "Coverage: ${COV}%"
+                        python3 -c "import sys; sys.exit(0 if float('$COV') >= 80 else 1)" \
+                            || { echo "Coverage below 80%"; exit 1; }
+                    '''
+
+                    // Export Cobertura for Jenkins plugin
+                    sh 'ucis show code-coverage merged.xml --output-format cobertura > coverage.xml'
+
+                    // Export JaCoCo (alternative)
+                    // sh 'ucis show code-coverage merged.xml --output-format jacoco > jacoco.xml'
+
+                    // Generate HTML report
+                    sh 'ucis report merged.xml -of html -o coverage_report.html'
+                }
+
+                post {
+                    always {
+                        // Publish Cobertura coverage
+                        cobertura coberturaReportFile: 'coverage.xml',
+                                  failUnhealthy: false,
+                                  failUnstable: false
+
+                        // Archive HTML report
+                        archiveArtifacts artifacts: 'coverage_report.html'
+                    }
+                }
+            }
+        }
+    }
+
+JaCoCo Variant
+==============
+
+Replace the Cobertura steps with:
+
+.. code-block:: groovy
+
+    sh 'ucis show code-coverage merged.xml --output-format jacoco > jacoco.xml'
+
+    post {
+        always {
+            jacoco execPattern: 'jacoco.xml'
+        }
+    }
+
+Verilator Projects
+==================
+
+.. code-block:: groovy
+
+    sh 'ucis merge --input-format vltcov -o merged.xml tests/*/coverage.dat'

doc/source/conf.py

@@ -39,13 +39,15 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinxcontrib.makedomain',
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.inheritance_diagram',
     'sphinx-jsonschema',
     'sphinx_issues',
     'sphinxarg.ext',
+    'sphinx_design',
     ]
 
 intersphinx_mapping = {

doc/source/getting-started/index.rst

@@ -0,0 +1,13 @@
+###############
+Getting Started
+###############
+
+PyUCIS is a Python toolkit for working with functional verification coverage data.
+It reads coverage output from simulators and verification frameworks, stores it in
+a unified format, and provides tools to explore, merge, report, and export that data.
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   quickstart