Skip to content

Commit c2d6f6e

Browse files
mballancemballance
authored
Merge pull request #42 from fvutils/mballance/doc-refactor
Refactor doc structure
2 parents 2a0992e + 9410986 commit c2d6f6e

38 files changed

Lines changed: 5821 additions & 28 deletions

‎doc/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ sphinxcontrib-makedomain
1010
sphinxcontrib-spelling
1111
sphinx-issues
1212
sphinx-argparse
13+
sphinx-design
1314

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
##########
2+
MCP Server
3+
##########
4+
5+
The PyUCIS MCP server lets AI assistants (such as Claude) query your coverage
6+
databases using natural language. Instead of memorizing command syntax, you
7+
can ask questions like:
8+
9+
* *"What is the overall coverage of my regression?"*
10+
* *"Which covergroups have the lowest coverage?"*
11+
* *"Show me all bins that were never hit."*
12+
* *"Compare today's run to yesterday's baseline and report any regressions."*
13+
* *"Export coverage as LCOV and tell me what genhtml command to run."*
14+
15+
The server uses the `Model Context Protocol (MCP) <https://modelcontextprotocol.io/>`_,
16+
a standard interface for connecting AI tools to external data sources.
17+
18+
Installation
19+
============
20+
21+
.. code-block:: bash
22+
23+
pip install pyucis[dev]
24+
25+
This installs the ``pyucis-mcp-server`` command and its dependencies.
26+
27+
Configuring Claude Desktop
28+
==========================
29+
30+
1. Find your Claude Desktop config file:
31+
32+
* **macOS**: ``~/Library/Application Support/Claude/claude_desktop_config.json``
33+
* **Linux**: ``~/.config/Claude/claude_desktop_config.json``
34+
* **Windows**: ``%APPDATA%\Claude\claude_desktop_config.json``
35+
36+
2. Add the PyUCIS server entry:
37+
38+
.. code-block:: json
39+
40+
{
41+
"mcpServers": {
42+
"pyucis": {
43+
"command": "pyucis-mcp-server"
44+
}
45+
}
46+
}
47+
48+
3. Restart Claude Desktop.
49+
50+
The PyUCIS tools are now available in your conversations.
51+
52+
Example Session
53+
===============
54+
55+
Once connected, open a coverage database by telling Claude the file path, then ask
56+
questions in plain English:
57+
58+
.. code-block:: text
59+
60+
You: Open /path/to/regression.xml and give me a coverage summary.
61+
62+
Claude: The database has 78.4% overall coverage across 142 covergroups.
63+
Functional coverage is 81.2%; code coverage is 74.6%.
64+
There are 23 covergroups below 50%.
65+
66+
You: Which covergroups have zero coverage?
67+
68+
Claude: The following 8 covergroups have 0% coverage: ...
69+
70+
You: Compare this to /path/to/baseline.xml and report regressions.
71+
72+
Claude: Compared to baseline, 3 items regressed: ...
73+
74+
Available Operations
75+
====================
76+
77+
The MCP server provides tools for:
78+
79+
* Opening, listing, and closing databases
80+
* Coverage summary, gaps, and metrics
81+
* Covergroup, coverpoint, and bin details
82+
* Design hierarchy navigation
83+
* Test execution history
84+
* Database comparison (regression detection)
85+
* Hotspot analysis
86+
* Code coverage export (LCOV, Cobertura, JaCoCo, Clover)
87+
* Assertion and toggle coverage
88+
89+
Starting the Server Manually
90+
============================
91+
92+
The server communicates via stdin/stdout and is normally started by the MCP
93+
client automatically. To start it manually for testing:
94+
95+
.. code-block:: bash
96+
97+
pyucis-mcp-server
98+
99+
See the `MCP specification <https://modelcontextprotocol.io/>`_ for client
100+
integration details beyond Claude Desktop.

‎doc/source/cicd/github-actions.rst‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
##############
2+
GitHub Actions
3+
##############
4+
5+
The examples below show a complete coverage workflow for GitHub Actions: run tests,
6+
merge coverage, export to Codecov, publish an HTML report artifact, and gate the
7+
build on a minimum coverage threshold.
8+
9+
Full Workflow Example
10+
=====================
11+
12+
.. code-block:: yaml
13+
14+
name: Coverage
15+
16+
on:
17+
push:
18+
branches: [main]
19+
pull_request:
20+
21+
jobs:
22+
coverage:
23+
runs-on: ubuntu-latest
24+
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- uses: actions/setup-python@v5
29+
with:
30+
python-version: "3.11"
31+
32+
- name: Install PyUCIS
33+
run: pip install pyucis
34+
35+
- name: Run tests
36+
run: make run_all_tests # produces test_*.xml or test_*.dat
37+
38+
- name: Merge coverage
39+
run: ucis merge -o merged.xml test_*.xml
40+
41+
- name: Check coverage threshold
42+
run: |
43+
COV=$(ucis show summary merged.xml -of json | jq -r '.overall_coverage')
44+
echo "Coverage: ${COV}%"
45+
python -c "import sys; sys.exit(0 if float('$COV') >= 80 else 1)" \
46+
|| (echo "Coverage below 80%" && exit 1)
47+
48+
- name: Export LCOV for Codecov
49+
run: ucis show code-coverage merged.xml --output-format lcov > coverage.info
50+
51+
- name: Upload to Codecov
52+
uses: codecov/codecov-action@v4
53+
with:
54+
files: ./coverage.info
55+
56+
- name: Generate HTML report
57+
run: ucis report merged.xml -of html -o coverage_report.html
58+
59+
- name: Upload HTML report artifact
60+
uses: actions/upload-artifact@v4
61+
with:
62+
name: coverage-report
63+
path: coverage_report.html
64+
65+
Verilator Projects
66+
==================
67+
68+
Replace the merge step if your tests produce ``.dat`` files:
69+
70+
.. code-block:: yaml
71+
72+
- name: Merge Verilator coverage
73+
run: ucis merge --input-format vltcov -o merged.xml tests/*/coverage.dat
74+
75+
Cobertura Upload
76+
================
77+
78+
If you prefer Cobertura (e.g. for GitHub code coverage annotations via a
79+
third-party action):
80+
81+
.. code-block:: yaml
82+
83+
- name: Export Cobertura
84+
run: ucis show code-coverage merged.xml --output-format cobertura > coverage.xml

‎doc/source/cicd/gitlab-ci.rst‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
##########
2+
GitLab CI
3+
##########
4+
5+
The example below shows a complete coverage workflow for GitLab CI: merge
6+
coverage, export Cobertura for the GitLab coverage visualization, and publish
7+
an HTML report as a job artifact.
8+
9+
Full Workflow Example
10+
=====================
11+
12+
.. code-block:: yaml
13+
14+
stages:
15+
- test
16+
- coverage
17+
18+
run_tests:
19+
stage: test
20+
script:
21+
- make run_all_tests # produces test_*.xml
22+
artifacts:
23+
paths:
24+
- test_*.xml
25+
26+
coverage:
27+
stage: coverage
28+
script:
29+
- pip install pyucis
30+
31+
# Merge
32+
- ucis merge -o merged.xml test_*.xml
33+
34+
# Coverage gate
35+
- |
36+
COV=$(ucis show summary merged.xml -of json | jq -r '.overall_coverage')
37+
echo "Coverage: ${COV}%"
38+
python3 -c "import sys; sys.exit(0 if float('$COV') >= 80 else 1)" \
39+
|| (echo "Coverage below 80%" && exit 1)
40+
41+
# Export Cobertura for GitLab coverage widget
42+
- ucis show code-coverage merged.xml --output-format cobertura > coverage.xml
43+
44+
# Generate shareable HTML report
45+
- ucis report merged.xml -of html -o coverage_report.html
46+
47+
coverage: '/Coverage:\s+(\d+\.\d+)%/'
48+
49+
artifacts:
50+
reports:
51+
coverage_report:
52+
coverage_format: cobertura
53+
path: coverage.xml
54+
paths:
55+
- coverage_report.html
56+
expire_in: 1 week
57+
58+
Verilator Projects
59+
==================
60+
61+
.. code-block:: yaml
62+
63+
- ucis merge --input-format vltcov -o merged.xml tests/*/coverage.dat

‎doc/source/cicd/index.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
################
2+
CI/CD Integration
3+
################
4+
5+
PyUCIS integrates cleanly into continuous integration pipelines. The typical
6+
pattern is:
7+
8+
1. Run tests — each test produces a coverage file
9+
2. Merge coverage files into a single database
10+
3. Export to the format your CI tool expects
11+
4. Optionally gate the build on a coverage threshold
12+
13+
.. toctree::
14+
:maxdepth: 1
15+
16+
github-actions
17+
gitlab-ci
18+
jenkins
19+
20+
For the available export formats see :doc:`../reporting/exporting`.

‎doc/source/cicd/jenkins.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
#######
2+
Jenkins
3+
#######
4+
5+
The declarative pipeline below merges coverage, publishes a Cobertura report
6+
via the Jenkins Cobertura plugin, and generates an HTML report artifact.
7+
8+
Prerequisites
9+
=============
10+
11+
Install the `Cobertura Plugin <https://plugins.jenkins.io/cobertura/>`_
12+
(or `JaCoCo Plugin <https://plugins.jenkins.io/jacoco/>`_) in Jenkins.
13+
14+
Full Pipeline Example
15+
=====================
16+
17+
.. code-block:: groovy
18+
19+
pipeline {
20+
agent any
21+
22+
stages {
23+
stage('Test') {
24+
steps {
25+
sh 'make run_all_tests' // produces test_*.xml
26+
}
27+
}
28+
29+
stage('Coverage') {
30+
steps {
31+
sh 'pip install pyucis'
32+
33+
// Merge all test coverage files
34+
sh 'ucis merge -o merged.xml test_*.xml'
35+
36+
// Coverage gate
37+
sh '''
38+
COV=$(ucis show summary merged.xml -of json | jq -r '.overall_coverage')
39+
echo "Coverage: ${COV}%"
40+
python3 -c "import sys; sys.exit(0 if float('$COV') >= 80 else 1)" \
41+
|| { echo "Coverage below 80%"; exit 1; }
42+
'''
43+
44+
// Export Cobertura for Jenkins plugin
45+
sh 'ucis show code-coverage merged.xml --output-format cobertura > coverage.xml'
46+
47+
// Export JaCoCo (alternative)
48+
// sh 'ucis show code-coverage merged.xml --output-format jacoco > jacoco.xml'
49+
50+
// Generate HTML report
51+
sh 'ucis report merged.xml -of html -o coverage_report.html'
52+
}
53+
54+
post {
55+
always {
56+
// Publish Cobertura coverage
57+
cobertura coberturaReportFile: 'coverage.xml',
58+
failUnhealthy: false,
59+
failUnstable: false
60+
61+
// Archive HTML report
62+
archiveArtifacts artifacts: 'coverage_report.html'
63+
}
64+
}
65+
}
66+
}
67+
}
68+
69+
JaCoCo Variant
70+
==============
71+
72+
Replace the Cobertura steps with:
73+
74+
.. code-block:: groovy
75+
76+
sh 'ucis show code-coverage merged.xml --output-format jacoco > jacoco.xml'
77+
78+
post {
79+
always {
80+
jacoco execPattern: 'jacoco.xml'
81+
}
82+
}
83+
84+
Verilator Projects
85+
==================
86+
87+
.. code-block:: groovy
88+
89+
sh 'ucis merge --input-format vltcov -o merged.xml tests/*/coverage.dat'

‎doc/source/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,13 +39,15 @@
3939
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
4040
extensions = [
4141
'sphinx.ext.autodoc',
42+
'sphinx.ext.napoleon',
4243
'sphinx.ext.intersphinx',
4344
'sphinxcontrib.makedomain',
4445
'sphinx.ext.autosectionlabel',
4546
'sphinx.ext.inheritance_diagram',
4647
'sphinx-jsonschema',
4748
'sphinx_issues',
4849
'sphinxarg.ext',
50+
'sphinx_design',
4951
]
5052

5153
intersphinx_mapping = {

‎doc/source/getting-started/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
###############
2+
Getting Started
3+
###############
4+
5+
PyUCIS is a Python toolkit for working with functional verification coverage data.
6+
It reads coverage output from simulators and verification frameworks, stores it in
7+
a unified format, and provides tools to explore, merge, report, and export that data.
8+
9+
.. toctree::
10+
:maxdepth: 1
11+
12+
installation
13+
quickstart

0 commit comments

Comments
 (0)