API Reference & Docs Generation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The flext-oracle-wms project employs a multi-layered approach to API reference and documentation generation, integrating automated discovery with declarative catalogs and standardized build tools. The system is designed to provide comprehensive coverage of over 320+ Oracle WMS Cloud entities, ensuring that both developers and automated data pipelines have access to up-to-date schema definitions and endpoint references.
Documentation is categorized into public surface documentation, generated module overviews, and technical reference guides. This ecosystem ensures that integration points, such as the Parent MRO chain and Singer protocol compatibility, are well-documented for enterprise-grade data integration.
Sources: README.md:14-18, src/README.md:16-18, tests/unit/oracle_wms_complete_discovery.py:10-15
Documentation Architecture
The project follows a "Living Documentation" philosophy where understanding and behavior updates are reflected in the docs within the same change cycle as the code. The build system utilizes mkdocs with various plugins to generate the final documentation site from source material and docstrings.
Documentation Components
| Component | Path / Location | Purpose |
|---|---|---|
| Public Surface | docs/index.md | High-level entry point for the project documentation. |
| API Reference | docs/api-reference/README.md | Master index for all technical API specifications. |
| Module Overview | docs/api-reference/generated/overview.md | Automatically generated map of module exports and hierarchies. |
| Entity Discovery | discovery.py | Logic for dynamic documentation of live Oracle WMS entities. |
| API Catalog | api_catalog.py | Declarative definitions of WMS endpoints and versions. |
Sources: README.md:14-18, src/flext_oracle_wms/README.md:27-31, AGENTS.md:58-62
Automated Build Pipeline
The project uses make verbs to manage the lifecycle of documentation generation. The make docs command triggers the build process using the configuration defined in pyproject.toml.
The diagram above illustrates how static source code, declarative catalogs, and runtime discovery contribute to the final API reference site.
Sources: README.md:23, pyproject.toml:68-88, tests/unit/oracle_wms_complete_discovery.py:382-400
Declarative API Catalog
A core part of the documentation is the api_catalog.py module, which contains comprehensive Oracle WMS API definitions. This catalog serves as a single source of truth (SSOT) for endpoint management, versioning (specifically LGF API v10), and categorization.
Key Catalog Categories
- Data Extract: APIs for bulk data retrieval.
- Entity Operations: Standard CRUD and status operations for WMS entities.
- Setup Transactional: Configuration and setup endpoints.
- Automation Operations: High-frequency automated task endpoints.
Sources: src/flext_oracle_wms/README.md:31, tests/unit/oracle_wms_complete_discovery.py:65-85
Dynamic Discovery & Schema Generation
For enterprise integration, the system performs "Complete Discovery" to generate technical documentation for the specific Oracle WMS instance. This includes automatic schema introspection and metadata extraction to define field types for over 320 entities.
Schema Discovery Process
This sequence shows how the system discovers live entity structures to generate accurate technical documentation and schemas.
Sources: tests/unit/oracle_wms_complete_discovery.py:326-360, src/flext_oracle_wms/README.md:43-48
Metadata Metadata Fields
The discovery process extracts the following metadata for API documentation:
- total_count: Number of records in the WMS instance.
- field_types: Mapping of Oracle field names to Python/JSON types.
- sample_data: Representative record structure.
- structure_available: Boolean indicating if the entity is active and populated.
Sources: tests/unit/oracle_wms_complete_discovery.py:302-324
Technical Standards for Documentation
The project enforces strict quality gates for documentation, managed through pyproject.toml and AGENTS.md.
- Docstring Compliance: All public functions and classes must have docstrings following enterprise standards.
- Zero-Tolerance for Stale Docs: Any change that modifies behavior must update affected documentation in the same PR.
- Executable Snippets: Markdown examples and docstring snippets are validated by
pytestplugins to ensure they remain functional.
Sources: AGENTS.md:58-62, pyproject.toml:238-245, src/README.md:118-122
Summary
API Reference and Documentation in flext-oracle-wms is a hybrid system that combines static declarative definitions (API Catalog) with runtime introspection (Entity Discovery). By utilizing MkDocs and strict "Living Documentation" rules, the project ensures that the technical reference remains a reliable, type-safe, and accurate representation of the underlying Oracle WMS Cloud infrastructure.
Sources: README.md:14-23, AGENTS.md:13-17, src/README.md:16-24