Skip to content

Adjust / Update api generator#1105

Merged
danielporterda merged 8 commits into
mainfrom
feature/adjust-api-generator
Jul 22, 2026
Merged

Adjust / Update api generator#1105
danielporterda merged 8 commits into
mainfrom
feature/adjust-api-generator

Conversation

@coldice

@coldice coldice commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

This PR adjusts and extends the reference doc generation process.

  1. Adjust API parameter table rendering - fix Parameters table in API docs are not rendered correctly #1005
  2. Add Daml Script API Reference doc generation - follow-up for add missing daml script reference page #846
  3. Update wallet references
  4. Fix JSON combine for Daml Standard Library - fix prelude.mdx is missing GHC.Types/GHC.Classes anchors linked from 44 splice-daml reference pages #1039

1. Adjust API parameter table rendering

API parameter tables are now rendered using the mintlify ResponseField component.
image
Files in ‎docs-main/appdev/reference/daml-standard-library/ have been regenerated with new parameter tables.

2. Add Daml Script API Reference doc generation

Follow-up from PR 1008, this implements the scripts, configuration and tests to generate the daml script api reference doc section. The generated files have already been added in the linked PR.

Also adds a shared library in scripts/lib/daml_docs_sdk.sh‎ which contains functions (install/damlc/LF resolution) moved out from scripts/generate_daml_standard_library_json.sh to also be reused for the daml script doc generation in scripts/generate_daml_script_json.sh.

3. Update wallet references

Updates repo links and references for hyperledger-labs/splice-wallet-kernel to canton-network/wallet

4. Fix JSON combine for Daml Standard Library

When combining daml-stdlib and daml-prim JSON for package_set: base, modules with the same name (from -- | MOVE annotations, e.g. Prelude) used first-wins and kept only the stdlib copy. That dropped prim-side types and classes such as Bool and Eq from the generated pages.

This PR fixes base JSON combine for Daml Standard Library: merge same-named modules from daml-stdlib and daml-prim (via scripts/merge_daml_docs_modules.py) so MOVE’d content is kept — restores missing Prelude / DA.Exception / DA.Stack entities. E.g. the Prelude page was missing entries for base types like Decimal, which are now present. Also the rendering has been adjusted to fix a few issues.

Also adjusts the rendering:

  • Render items like Decimal = Numeric 10 in two lines, fix rendering in right sidebar
  • Add internal links within the docs pages (adds a pre-step to generate a file index)
  • Fixes an issue with the rendering of % signs in codeblocks in headlines (added a work-around)
image

@mintlify

mintlify Bot commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
cantonfoundation 🟢 Ready View Preview Jul 20, 2026, 8:20 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@mintlify

mintlify Bot commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
cantonfoundation 🟡 Building Jul 20, 2026, 8:18 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

…e/parameter rendering

update api ref doc generator, add support for type merge, adjust special character rendering
update config, update splice wallet kernel references
update standard library reference docs, add internal linking

Signed-off-by: Ibo Sy <ibo@b9lab.com>
@coldice
coldice force-pushed the feature/adjust-api-generator branch from 21c223b to 1c525ac Compare July 20, 2026 22:45
@coldice
coldice marked this pull request as ready for review July 20, 2026 22:50
Signed-off-by: Ibo Sy <ibo@b9lab.com>
@danielporterda

Copy link
Copy Markdown
Contributor

I found one hosted-preview regression in the % function-heading workaround.

The generated source uses ### <code>{'\\u0025'}</code>. On the PR preview at that function, Mintlify visibly renders %, but inspection of the actual rendered heading shows:

<h3 id="">
  <a href="#" aria-label="Navigate to header"></a>
  <span><code>%</code></span>
</h3>

I also tested the permalink directly. Before clicking it, the URL was:

…/prelude#function-ghc-num-x-53920

After clicking the heading's permalink, it became:

…/prelude#

The explicit <span id="function-ghc-num-x-53920"> immediately before the heading means links emitted by the generator still reach the right location, but Mintlify's own heading id/permalink is empty and unusable.

Could we render a slug-bearing plain-text heading—such as ### Operator %—while retaining the % code-formatted signature below it, and add a regression check that the hosted/rendered heading gets a non-empty permalink?

Signed-off-by: Ibo Sy <ibo@b9lab.com>
@coldice

coldice commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Hey @danielporterda good catch - unfortunately, we can not render a % at all in the headlines (always produces a mintlify render error). And because this is formatted in a codeblock, we can also not use other escape characters. So following your proposal, I think the only feasible solution is to drop the "%" completely and just write "modulo" or "modulo operator" for this one. I have added an update, rendering "modulo" instead.

@danielporterda
danielporterda merged commit 4700a11 into main Jul 22, 2026
4 checks passed
@danielporterda
danielporterda deleted the feature/adjust-api-generator branch July 22, 2026 20:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

3 participants