-
Notifications
You must be signed in to change notification settings - Fork 254
fix: update Flux help #6170
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
fix: update Flux help #6170
Changes from all commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
a0664b3
fix: example style rendering
alespour 9c7c4be
fix: update Flux help
alespour 486e23f
feat: Flux help patch generator
alespour 98696b0
Revert "fix: update Flux help"
alespour 4e9a9a9
fix: adjust formatting to make eslint happy
alespour f86cfd5
fix: generator rules
alespour 8896d8c
fix: update Flux help
alespour b3f193c
docs: update CHANGELOG
alespour ae0f003
wip: e2e workflow troubleshooting
alespour 9923044
Revert "fix: update Flux help"
alespour a66a208
Revert "fix: example style rendering"
alespour d923458
Revert "wip: e2e workflow troubleshooting"
alespour 0eaca5b
fix: examples are insertable
alespour f49c399
fix: improved example formatting
alespour 00df980
fix: remove trailing comma in examples
alespour 2f6495e
docs: update CHANGELOG.md
alespour File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| Flux Help Sync Script README | ||
|
|
||
| Overview | ||
| This script generates a unified diff that synchronizes Flux function help | ||
| entries in `ui/src/flux/constants/functions.ts` with the Flux v0 docs from the | ||
| local docs-v2 repository. | ||
|
|
||
| Files and Paths | ||
| - Script: `scripts/flux-help-sync.py` | ||
| - Input help file: `ui/src/flux/constants/functions.ts` | ||
| - Docs repo (default): `../docs-v2` (override with `--docs-v2-repo-dir`) | ||
| - Docs stdlib root: `../docs-v2/content/flux/v0/stdlib` | ||
| - Output patch: `flux-help.diff` (repo root) | ||
|
|
||
| How it works | ||
| 1) It scans the docs tree and builds a map of functions using: | ||
| - front matter `title` and `description` | ||
| - the `## Parameters` section | ||
| - the `Function type signature` block | ||
| - the first relevant JavaScript example (multi-line preserved) | ||
| - front matter `flux/v0/tags` for category inference | ||
| 2) It loads `functions.ts` by evaluating it in a Node VM to collect existing | ||
| help entries. | ||
| 3) It updates existing entries with doc-derived content and appends new entries | ||
| for functions present in docs but missing in `functions.ts`. | ||
| 4) It writes the diff to `flux-help.diff`. It does not modify `functions.ts`. | ||
|
|
||
| Usage | ||
| - Generate a patch: `python scripts/flux-help-sync.py` | ||
| - Tag undocumented stubs: `python scripts/flux-help-sync.py --tag-undocumented` | ||
| - Prune undocumented entries: `python scripts/flux-help-sync.py --prune-undocumented` | ||
| - Prune only removed entries: `python scripts/flux-help-sync.py --prune-removed` | ||
| - Set docs-v2 repo location: `python scripts/flux-help-sync.py --docs-v2-repo-dir /path/to/docs-v2` | ||
| - Set output path: `python scripts/flux-help-sync.py --output /path/to/flux-help.diff` | ||
|
|
||
| Undocumented stubs | ||
| - If `--tag-undocumented` is used and a function has no matching documentation page, | ||
| its description is tagged with `(Undocumented)` or set to | ||
| `Undocumented function.`. | ||
| - This only affects functions already present in `functions.ts`. | ||
|
|
||
| Pruning | ||
| - `--prune-undocumented` removes entries missing documentation pages. | ||
| - `--prune-removed` removes entries missing documentation pages only if listed as removed | ||
| in `content/flux/v0/release-notes.md` under the docs repo root. | ||
|
|
||
| Notes and assumptions | ||
| - The docs root defaults to `../docs-v2`. Override it with `--docs-v2-repo-dir`. | ||
| - The script skips `_index.md` and `all-functions.md`. | ||
| - It omits the `tables` parameter when the signature shows a piped input | ||
| (`<-tables`). | ||
| - Examples are always updated from docs for entries with matching pages. | ||
| - Examples are extracted from the first JavaScript example block by locating | ||
| the first call to the function and reducing it to a single-line call | ||
| expression (no pipeline, imports, or setup). Full-line and inline `//` | ||
| comments are removed before extracting the call. Trailing commas before a | ||
| closing parenthesis are removed. If no call is found, new entries default to | ||
| `functionName()`, and existing entries keep their current example. | ||
| - Links are sourced directly from docs-v2 paths (for example, | ||
| `.../flux/v0/stdlib/universe/...`) and existing entries are updated to match. | ||
| - Strings are quoted using single or double quotes to satisfy Prettier when | ||
| apostrophes are present. | ||
| - If multiple doc pages share the same function name, the script prefers | ||
| non-deprecated entries. If descriptions differ, it keeps all unless the | ||
| only difference is a contrib variant (for example `from`), in which case it | ||
| prefers the non-contrib entry. Otherwise, it prefers non-experimental, | ||
| non-contrib, and prelude packages. | ||
| - Variant entries for input-source splits (for example `csv.from`) are defined | ||
| explicitly in `VARIANT_SPECS` in the script. | ||
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.