Skip to content

Standardize KDF doc styles to facilitate bidirectional docs/postman integration.#511

Draft
smk762 wants to merge 159 commits intodevfrom
add/postman/utils
Draft

Standardize KDF doc styles to facilitate bidirectional docs/postman integration.#511
smk762 wants to merge 159 commits intodevfrom
add/postman/utils

Conversation

@smk762
Copy link
Contributor

@smk762 smk762 commented Jun 5, 2025 •
edited
Loading

New Files*

  • Adds misc missing methods (list TBA)
  • Creates misc new common structures and enums (list TBA)
  • Adds openAPI yaml spec files for all methods, structures. error types and enums
  • Adds json request example bodies for shared use between postman & mdx docs.

Folder structure changes

  • JS and PY scripts all moved under utils folder.
  • Text or json data imported/exported from scripts now sit under js/data or py/data, except in some cases where moving these files breaks CI/CD.
  • Repo docs (style guide, ai prompts etc) now sit under docs folder

KDF Method docs structure changes

  • Added required and default columns to KDF method param tables.
  • Standardized Page titles, headings, subheadings.
  • Standardized Request, Response, Structure and Enum tables.
  • Standardized CodeGroup and CollapsibleSection component usage
  • Decoupled all multi-method files. It is now "One method, one file". Where appropriate, overviews for method groups have been included to allow for more detail about using the group as a whole.

Utils/scripts updates

  • Adds some utility scripts to assist with ETL ops between OpenAPI, Postman and MDX
  • JS scripts updated to use common path variables to avoid path issues.
  • Slug validation tweaked to ensure consistent use of KDF method names in the ## header
  • Updated redirect map with respect to recent folder changes.

AI related

  • Adds cursor rules and style guide entries to guide AI assisted mdx file refactoring into standardised structures for simplified parsing/injection. This can be performed in batches across a list of files, or on single files after they are drafted so they can be verified as compliant with standards before merge.
  • adds docs/prompts folder for potentially useful reusable AI prompts for specific actions.

TODO:

  • add docker container for newman/postman/kdf to test all methods examples and keep json requests/responses fresh
  • add reliable pipeline between KDF repo and docs repo to reduce doc update lag time, and validate docs examples.
  • add style validation CI/CD tests

@smk762 smk762 added the house keeping something needs cleaning up label Jun 5, 2025
@smk762 smk762 self-assigned this Jun 5, 2025
@smk762 smk762 marked this pull request as draft June 5, 2025 06:13
@github-actions
Copy link

github-actions bot commented Jun 5, 2025 •
edited
Loading

Documentation Preview Links

Preview for commit: e3e644e
Base URL: https://5aafb35e.komodo-docs.pages.dev/en/docs

Changed Documentation Files

Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez
Commit: f062c67 - move common structurez

@smk762 smk762 force-pushed the add/postman/utils branch from 43a4535 to 6d39464 Compare June 7, 2025 19:50
smk762 and others added 21 commits July 1, 2025 10:18
@smk762 smk762 mentioned this pull request Jul 30, 2025
Closed
@smk762 smk762 mentioned this pull request Aug 5, 2025
Merged
@smk762
Copy link
Contributor Author

smk762 commented Aug 11, 2025

This PR is now "reference only". Parts will be incrementally borrowed for new smaller PRs towards the same end goal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@smk762 smk762

Labels

discussion do not merge house keeping something needs cleaning up

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@smk762