Feature/documentation - #726
Open
a-frankl wants to merge 11 commits into
Open
Conversation
… level tracdap's docs should describe the project - what's open source and how the pieces relate - not serve as an operational guide to deploying the full platform, which fintrac's own commercial documentation already covers. - Remove app_dev/ (platform-facing app tutorials, assumes a deployed gateway and superseded default auth, not maintained) - Remove deployment/ (auth docs describe a superseded mechanism, platform.rst is an acknowledged stub, and no file here adds up to a complete deployment guide) - Drop reference/index.rst now that it's a wrapper around exactly three auto-generated listings; promote model_api_python, metadata_listing and service_listing to top-level sections directly - Update root index.rst landing grid and toctree, and wire model_api_python into modelling/index.rst See Notes/tracdap-docs-restructuring.md (fintrac-documentation repo) for the full rationale and remaining sequencing.
.col-lg-3 (the left nav column) has flex-shrink:0, and .toc a had no width/wrap constraint, so a long unbreakable identifier (e.g. some tracdap.api class names like MetadataWriteBatchResponse) could push the sidebar past its 25% width. Since it can't shrink back, the row wraps and the main content stacks below the sidebar instead of sitting beside it. Reproduced on tracdap.finos.org's Service Listing pages at normal zoom. Constrain .site-toc .toc a to wrap instead of forcing the column wider.
…eApi Both services had no per-method documentation in the proto source (storage.proto had no comments at all, not even at service level), so Service Listing rendered these methods with no description - just the auto-generated parameter list. Comments are written from the request/response schema and follow the existing style in metadata.proto/data.proto, including the streaming vs. unary pairing already documented there for readFile/readSmallFile. Kept deliberately brief, matching this file's simpler, lower-level operations rather than the longer multi-paragraph style used for the metadata write API.
The previous commit documented TracStorageApi's RPC methods, but the message types those methods use (StorageRequest, StorageReadResponse, FileStat, etc.) had no comments either, so the Service Listing classes table rendered them with no description. Comments are written from the message's fields and its role in the surrounding RPC calls.
The autoapi module template listed every class in a single flat "Classes" table, alphabetically interleaving gRPC service interfaces (TracMetadataApi, TracStorageApi, etc.) with the request/response message types they use. For tracdap.api this made Service Listing hard to scan - 5 services buried among dozens of messages. Classify each class as a service if it has method children and isn't an Enum subclass (enum value assignments were briefly misclassified as methods during testing - excluded explicitly). Modules with no services (e.g. tracdap.metadata) just show the Messages section as before, so this doesn't change anything outside tracdap.api.
…isting, Model API, Modelling Tutorial Drops the modelling/index.rst wrapper page - Model API (Python) and the Modelling Tutorial are now separate top-level sections instead of both being nested under a single "Modelling" entry, matching how Service Listing and Metadata Listing already sit at the top level. Moves the "TRAC Runtime for Python is on PyPI" note from the now-removed wrapper page onto the tutorial's own landing page, and fixes the one dangling :doc: reference to modelling/index in overview/key_concepts.rst.
Rewrite the introduction page, fold metadata_model into the overview nav, and drop the separate key_concepts page as part of flattening the top-level nav. Also fixes a short heading underline and seven broken :class:/:meth: cross-references in metadata_model.rst that were using the wrong module prefix (trac.* instead of tracdap.*), which silently degraded them from links to plain text.
…nology Split Chapter 1 (Hello World) into Local Setup and Hello World, and Chapter 4 (Inputs & Outputs) into Optional Inputs & Outputs and Dynamic Schemas, so each chapter covers one topic. Renumbers the remaining chapters and fixes chaining.rst's cross-reference, which pointed to hello_world for repository layout content that now lives in local_setup. Also resolves 45 bare "TRAC" references across the tutorial pages using an explicit convention: "the runtime" for behavioral/execution statements (schema validation, type conversion, flow wiring), and "TRAC D.A.P." for product-level statements (install intros, version references, the metadata store). Fixes two incidental typos found along the way (aTRAC -> a, thw -> the).
…acy, terminology - Drop hardcoded "Chapter N -" title prefixes; numbering is now handled by the tutorial index's own toctree (:numbered: 1), scoped to chapter titles only - Merge "Wrapping Models" into "Using Data" as one chapter - the former was a thin preamble to the same example and didn't stand on its own - Add four new tutorial chapters: Using Files, Using STRUCTS, Using Polars, Runtime Metadata; reorder the toctree to group them logically - Rename "File Inputs & Outputs" -> "Using Files" and "Structured Data" -> "Using STRUCTS" for consistency with the "Using X" naming used elsewhere - Fix local_setup.rst: PySpark is declared as an extra in setup.cfg but has no working implementation (read/write_spark_table are unimplemented stubs), so drop it from the install instructions; treat Pandas/Polars symmetrically as optional dataframe extras instead of singling Pandas out; note NumPy is pulled in automatically with the pandas extra; add upper version bounds for Pandas/NumPy that were missing; add a section on installing third-party packages a model needs (e.g. Matplotlib) that aren't part of the runtime's own dependencies at all - Add an intro to local_setup.rst explaining these tutorials build models locally with no code changes needed to run on the platform - Replace inconsistent "sandbox" wording with "locally"/"dev mode" to match terminology used throughout the rest of the tutorials - Expand hello_world.rst to actually define dev mode: the runtime infers metadata (object IDs, storage definitions, schemas) instead of requiring it up front, enabled by default in launch_model() vs. the --dev-mode flag needed on the command-line launcher
- Swap the shared banner image for a distinct runtime_logo.png (recolored
icon + explicit "tracdap-runtime" label), replacing the old tracmmp
banner across all 5 READMEs; fix the alt text to match
- Rewrite the main README intro ("Universal Model Runtime") and
Documentation section wording
- Use "Fintrac Limited" as the linked maintainer name in the License and
Enterprise sections, and clarify Enterprise support is for the trac
platform specifically
- Fix PROJECT_DESCRIPTION in all 4 extension _settings.py files: "TRAC
D.A.P." -> "tracdap-runtime", since these extensions plug into the
runtime package, not the platform as a whole
- Align extension README banners/body text with the same "tracdap-runtime"
naming, and drop the "pre-release, finalized in TRAC 0.10" line now
that 0.10 has shipped
- Replace remaining ambiguous bare "TRAC" mentions (used as a stand-in for
the runtime) with "the runtime" / "tracdap-runtime" throughout; leave
intact established compound terms that name distinct, real things
(TRAC platform, TRAC model, TRAC secrets mechanism)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Updates to the tracdap documentation for the 0.10 release, including;