7 - NextGenHealth: From Code to Clarity — How Unit Tests and Sphinx Built My Self-Documenting Healthcare API

Why Documentation Must Be Automated

In regulated environments like healthcare (HIPAA/GDPR), traceability is non-negotiable.

But manual documentation drifts. Outdated docs are worse than no docs.

So I turned to Sphinx, the same tool used by Django, FastAPI, and Python itself, to generate fully automated, versioned API documentation — straight from my codebase.

No copy-paste. No outdated diagrams. Just truth extracted from working code.

The Role of Unit Tests: Validation, Not Documentation

My unit tests are not part of the Sphinx-generated site.

They don’t appear in navigation menus or class references.

But they play a critical role: they validate that the documented behavior is real.

For example:

• The ValidEmailSpecification docstring says it enforces RFC-like format

• The corresponding test proves it by asserting rejection of invalid formats

This separation is intentional:

✅ Sphinx documents: "What the system does"

✅ Pytest verifies: "That it actually works"

Together, they form a powerful feedback loop between design and implementation.

Real-Time Result: Live API Docs You Can Trust

My entire domain layer — from User entity to ValidEmailSpecification — is now automatically documented and publicly accessible:

🔗 https://python-projects-fernando.github.io/nextgenhealth/

Explore it and see:

• The full User class with constructor validation

• Specification pattern in action (AndSpecification, NotSpecification)

• Custom exceptions and enums

This isn't static HTML — it's a living reference that evolves with every commit.

And because I have 87%+ test coverage, you can trust that what’s documented is what runs.

How I Built It

1. Docstrings as Contracts

Every class starts with a precise docstring:

These aren’t comments — they’re the source of truth for the API docs.

2. Sphinx Configuration

Using conf.py, I pointed Sphinx to my source:

sys.path.insert(0, os.path.abspath('../../../src'))

With extensions enabled:

extensions = [

'sphinx.ext.autodoc',

'sphinx.ext.viewcode',

'sphinx.ext.napoleon',

]

3. CI/CD Automation

I integrated everything into GitHub Actions:

✅ On every git push to main:

• Run all unit tests with make test

• Generate coverage report (make coverage)

• Build Sphinx docs

• Deploy to gh-pages

• Site updates automatically at *.github.io

No manual steps. No outdated docs.

Benefits Beyond Compliance

✅Onboarding Acceleration - New devs explore API directly, no tribal knowledge

✅Audit Readiness - Full traceability: requirement → code → test → doc

✅Refactoring Confidence - Docs update automatically — no drift

✅Client Trust - Shows rigor in design and delivery

It’s Engineering Discipline

Documentation generated this way:

• Scales with the system

• Enforces consistency

• Prevents knowledge silos

• Aligns with SDLC phases

It turns my codebase into a self-explaining system — exactly what enterprise healthcare software demands.

And when combined with unit-tested domain logic, it becomes proof of quality.

Stay in the Loop

Want to follow the journey?

🔗 Connect on LinkedIn — I post updates on architecture decisions, UML modeling, and healthcare compliance.

📧 Need expert help on your healthcare project?

Let’s talk: contact@fmbyteshiftsoftware.com

Check the full project changelog:
👉 Change Log

📁 GitHub NextGenHealth Project

NextGenHealth’s API Documentation:

🔗 https://python-projects-fernando.github.io/nextgenhealth/

Code. Design. Document. Refine.

About the Author: Fernando Antunes de Magalhães is a Software Architect with over 15 years of experience, including 11 years focused on healthcare technology. He holds a Post-Graduate degree in Software Engineering and is the author of “Software Engineering — Essential Principles for Beginners and Professionals” (link). As CEO of FM ByteShift Software, he builds next-generation systems with precision, compliance, and real-world impact.