Skip to content

doc: update documentation for ontology-driven architecture - #401

Merged
JessUWE merged 22 commits into
mainfrom
docs/update-ontology-architecture
Aug 11, 2026
Merged

doc: update documentation for ontology-driven architecture#401
JessUWE merged 22 commits into
mainfrom
docs/update-ontology-architecture

Conversation

@JessUWE

@JessUWE JessUWE commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

This PR updates the ACRO documentation to reflect the new ontology-driven architecture introduced. The changes explain how ACRO's disclosure checking has moved from hard-coded logic to an ontology-driven approach, making it more maintainable, auditable, and extensible.

Changes

New Files

  • docs/source/user_guide/architecture.rst - Detailed technical architecture reference for developers and TRE administrators
    • Explains the four JSON knowledge files (analyses.json, statbarns.json, risks.json, checks.json)
    • Documents core classes: SDCChecks, TableModelDetails, SDCEvidence, ChecksResults, ManyChecksResults
    • Details suppression via data redaction and category preservation
    • Covers federated evidence serialisation
    • Guides adding new analysis types

Updated Files

API Documentation

  • docs/source/api.rst - Enhanced with new sections on ontology-driven checking classes (SDCChecks, SDCEvidence, ChecksResults, ManyChecksResults, TableModelDetails)
  • docs/source/api/acro_class.rst - Expanded with complete method documentation including mitigation control methods (enable_suppression, disable_suppression, enable_rounding, disable_rounding)
  • docs/source/api/records_class.rst - Added module-level functions and detailed class documentation

Landing Pages

  • docs/source/index.rst - Updated release note highlighting ontology-driven architecture
  • docs/source/introduction.rst - explanation of principles-based SDC and three-phase pipeline

User Guide

  • docs/source/user_guide.rst - Improved navigation and structure with clear learning paths
  • docs/source/user_guide/getting_started.rst - Beginner-friendly guide with complete workflow examples
  • docs/source/user_guide/core_concepts.rst - Deep dive into SDC principles, new architecture classes, and design patterns
  • docs/source/user_guide/configuration.rst - configuration guide with tables, examples, and precedence rules

@codecov

codecov Bot commented Jul 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.81%. Comparing base (f4173ed) to head (fbf0ea6).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #401      +/-   ##
==========================================
+ Coverage   99.75%   99.81%   +0.05%     
==========================================
  Files          10       15       +5     
  Lines        1602     2107     +505     
==========================================
+ Hits         1598     2103     +505     
  Misses          4        4              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
@JessUWE JessUWE changed the title docs: update documentation for ontology-driven architecture (v0.4.12) docs: update documentation for ontology-driven architecture Jul 24, 2026
Comment thread docs/source/user_guide/architecture.rst Outdated
Comment thread docs/source/user_guide/architecture.rst
Comment thread docs/source/user_guide/architecture.rst
Comment thread docs/source/user_guide/architecture.rst
Comment thread docs/source/user_guide/core_concepts.rst Outdated
Comment thread docs/source/user_guide/getting_started.rst Outdated
Comment thread docs/source/api.rst Outdated
Comment thread docs/source/api.rst
Comment thread docs/source/api.rst Outdated
Comment thread docs/source/api.rst Outdated
Comment thread docs/source/api.rst Outdated
Comment thread docs/source/api.rst Outdated
JessUWE and others added 5 commits August 7, 2026 12:21
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>

@jim-smith jim-smith left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a very few minor things to change/suggestions otherwise good to go. Much improved

JessUWE and others added 4 commits August 7, 2026 17:55
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Clarify steps for adding methods to ACRO class and handling analyses.

Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
@JessUWE
JessUWE requested a review from jim-smith August 11, 2026 08:34
Comment thread docs/source/user_guide/core_concepts.rst Outdated
Comment thread docs/source/user_guide/core_concepts.rst Outdated
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Comment thread docs/source/user_guide/core_concepts.rst Outdated
JessUWE and others added 2 commits August 11, 2026 13:11
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
Comment thread docs/source/user_guide/getting_started.rst Outdated
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
@JessUWE JessUWE changed the title docs: update documentation for ontology-driven architecture doc: update documentation for ontology-driven architecture Aug 11, 2026
Comment thread docs/source/user_guide/getting_started.rst Outdated
Co-authored-by: Jim-smith <jim-smith@users.noreply.github.com>
Signed-off-by: Jessica Ikechukwu <Jessica.Ikechukwu@uwe.ac.uk>
@JessUWE
JessUWE requested a review from jim-smith August 11, 2026 12:18
Comment thread docs/source/user_guide/getting_started.rst Outdated

@jim-smith jim-smith left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

couple of minor tweaks please.

  • I'm worried that we might give the impression the safety parameters can be changed by researchers
  • statbarnsdc already covers 114/5 types of analysis, and any changes to the ontology need to go through a strict approval process. So we need to make clear that we are talking about how people implement code to support functions already present in statbarnssdc

@JessUWE
JessUWE requested a review from jim-smith August 11, 2026 13:22
@JessUWE
JessUWE merged commit e880faa into main Aug 11, 2026
3 checks passed
@JessUWE
JessUWE deleted the docs/update-ontology-architecture branch August 11, 2026 14:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants