OpenSTA mddocs Cursor session export (Aug 2026)

opensta-mddocs-session.md

OpenSTA Markdown docs Cursor session

Transcript id: abd6762a-65a0-4aaf-a828-ddebcfa334d4 Dates: 2026-08-10 through 2026-08-14 Repo: akashlevy/OpenSTA (fork of parallaxsw/OpenSTA) Branch: mddocs PR: parallaxsw/OpenSTA#487 Preview: https://www.akashlevy.com/OpenSTA/

This is an export of the Cursor session that produced the MkDocs / Tcl-help documentation work.

User requests (in order)

1. 2026-08-10 — Migrate the entire doc/ directory to Read the Docs-ready Markdown.
2. 2026-08-10 — Plan automated conversion from .fodt. Prefer generating command docs from Tcl, and have help <command> show the same text. Also CLI args. Asked whether that was a good idea.
3. 2026-08-13 — Command descriptions should live in Tcl (define_cmd_args -help), extracted programmatically. Implement the full pipeline: help DB, rewrite help, generate commands.md / command-line.md / variables.md, CMake + CI drift checks.
4. 2026-08-14 — Implement the attached plan. Do not edit the plan file. Keep doc/CLA.txt intact (CLA bot).
5. 2026-08-14 — Create a venv and serve the docs locally.
6. 2026-08-14 — Filter expressions || rendering was wrong.
7. 2026-08-14 — Backticks around commands, options, and identifiers in help strings so they render as teletype.
8. 2026-08-14 — changelog.md HTML was messy (ticks, Emacs Local Variables footer).
9. 2026-08-14 — Undocumented commands must not appear in Markdown/HTML.
10. 2026-08-14 — STA API directory list rendered as a cascading definition list.
11. 2026-08-14 — Enum option help such as -path_delay should be nested lists, not one long line.
12. 2026-08-14 — Enforce that every option on a documented command has help; fill gaps from code. Exclude undocumented commands.
13. 2026-08-14 — Clean up coding guidelines and API changes (teletype, tables, fences).
14. 2026-08-14 — Which undocumented commands are worth documenting (not internal / not niche)?
15. 2026-08-14 — Document the recommended set, plus optional ones, plus deprecated ones with pointers to replacements.
16. 2026-08-14 — Audit remaining docs for discrepancies; then fix all buckets.
17. 2026-08-14 — Rename cmd_help_allowlist to indicate hidden commands.
18. 2026-08-14 — Branch mddocs, push to akashlevy/OpenSTA, GitHub Pages preview off this branch, detailed PR with session export.
19. 2026-08-14 — Make sure all tests are passing for the PR; are they running in CI properly?
20. 2026-08-14 — Sync upstream/master into fork master, merge master into mddocs, document any new commands, push, re-export this session to the same gist, then fix CI in a loop.

Architecture that landed

Tcl is the source of truth. Markdown under doc/ is a committed artifact. Read the Docs and GitHub Pages only run MkDocs.

define_cmd_args -help/-arg_help  →  cmd_help / cmd_arg_help
define_var_help                  →  var_help / var_values
define_common_arg_help           →  shared option text
         ↓
help command (runtime) + etc/WriteCmdDocs.tcl → doc/commands.md, variables.md, command-line.md
etc/FindMessages.tcl → doc/messages.md
etc/CheckCmdHelp.tcl → CI: every exported command is documented or listed as hidden;
                       every synopsis option on a documented command has help

help strips Markdown (backticks) for the terminal via md_help_to_text. After Tcl help edits, rebuild sta so POST_BUILD regenerates docs.

Hidden commands (intentionally omitted from commands.md)

report_constant, report_path, set_ideal_net, show_copying, show_splash, show_warranty, write_gate_gnuplot, write_gate_spice.

Newly documented commands (were missing from the old OpenOffice manual)

• Recommended: get_modes, set_scene, define_property, set_property, unset_clock_groups, report_arrival, report_required, report_slack, report_object_full_names, report_object_names, log_begin, log_end, make_port, set_voltage
• Optional / specialist: included with the recommended set
• Deprecated (with pointer to replacement): define_corners → define_scene, read_power_activities → read_vcd, set_clock_sense → set_sense

Commands already on master before this work that have help and appear in commands.md: set_path_margin, set_max_dynamic_power, set_max_leakage_power.

Git / PR

• Fork remote: origin = akashlevy/OpenSTA
• Upstream remote: upstream = parallaxsw/OpenSTA
• Branch mddocs at 1ca36561 (FEATURE commit 9d39725f, then merge of upstream delay-calc, then messages.md regen)
• Fork master fast-forwarded to upstream/master (c3e09203) and pushed 2026-08-14
• Merge of master into mddocs was already up to date (those two C++ commits were already merged for the message-line-number CI fix)
• No new Tcl commands in the upstream delta (#486 PrimaDelayCalc + constant-disabled-arc slew merge). CheckCmdHelp.tcl is clean locally.

CI

Workflow .github/workflows/ci.yml on push and pull_request:

• linux-ubuntu: build, git diff --exit-code on generated md, CheckCmdHelp.tcl, test/regression
• linux-centos: Docker CentOS 7 test/regression
• macos: brew build + test/regression
• docs: mkdocs build --strict

PR checks out the merge of mddocs into parallaxsw/OpenSTA master. The first PR ubuntu failure was doc/messages.md line-number drift from those two upstream C++ commits; that is why mddocs merged upstream and regenerated messages before the fork master sync.

Preview

• GitHub Pages from mddocs via .github/workflows/gh-pages.yml → gh-pages branch
• https://www.akashlevy.com/OpenSTA/
• https://akashlevy.github.io/OpenSTA/