Add auto-generated human-readable Postman collection docs

[jordanpadams]

🗒️ Summary

Adds a Python script and GitHub Actions workflow to automatically generate a human-readable Markdown version of docker/postman/postman_collection.json whenever it is updated in a PR.

The generated postman_collection.md includes:

• Table of contents with folder hierarchy and HTTP method badges
• Per-request: method, full URL (path variables resolved), Accept header
• Test assertions with linked TestRail case IDs
• GitHub issue references as hyperlinks

Also excludes postman_collection.md from the end-of-file-fixer pre-commit hook (auto-generated file).

🤖 AI Assistance Disclosure

• No AI assistance used
• AI used for light assistance (e.g., suggestions, refactoring, documentation help, minor edits)
• AI used for moderate content generation (AI generated some code or logic, but the developer authored or heavily revised the majority)
• AI generated substantial portions of this code

Estimated % of code influenced by AI: 95%

⚙️ Test Data and/or Report

The generated docker/postman/postman_collection.md is committed alongside the JSON and can be reviewed directly in this PR.

♻️ Related Issues

Fixes #497

🤓 Reviewer Checklist

Documentation and PR Content

• Documentation: README, Wiki, or inline documentation (Sphinx, Javadoc, Docstrings) have been updated to reflect these changes.
• Issue Traceability: The PR is linked to a valid GitHub Issue
• PR Title: The PR title is "user-friendly" clearly identifying what is being fixed or the new feature being added, that if you saw it in the Release Notes for a tool, you would be able to get the gist of what was done.

Security & Quality

• SonarCloud: Confirmed no new High or Critical security findings.
• Secrets Detection: Verified that the Secrets Detection scan passed and no sensitive information (keys, tokens, PII) is exposed.
• Code Quality: Code follows organization style guidelines and best practices for the specific language (e.g., PEP 8, Google Java Style).

Testing & Validation

• Test Accuracy: Verified that test data is accurate, representative of real-world PDS4 scenarios, and sufficient for the logic being tested.
• Coverage: Automated tests cover new logic and edge cases.
• Local Verification: (If applicable) Successfully built and ran the changes in a local or staging environment.

Maintenance

• Backward Compatibility: Confirmed that these changes do not break existing downstream dependencies or API contracts (or that breaking changes are clearly documented).

[Copilot]

Pull request overview

Adds automation to generate and commit a human-readable Markdown rendering of the Postman collection JSON to improve PR reviewability and traceability.

Changes:

• Added docker/postman/generate_collection_docs.py to convert postman_collection.json into a structured Markdown document (TOC, requests, Accept headers, tests, links).
• Added a GitHub Actions workflow to regenerate and auto-commit postman_collection.md when the collection JSON changes on non-main branches.
• Updated pre-commit configuration to exclude the generated Markdown from end-of-file-fixer.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docker/postman/postman_collection.md	New auto-generated Markdown documentation output committed alongside the JSON.
docker/postman/generate_collection_docs.py	Script that parses the Postman collection JSON and renders Markdown with TOC, request details, and linkification.
.github/workflows/postman-collection-docs.yml	CI workflow to regenerate and commit the Markdown when the collection JSON changes.
.pre-commit-config.yaml	Excludes the generated Markdown file from the EOF fixer hook.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

extract_test_names() only detects pm.test() calls where the first argument is wrapped in single/double quotes. The current collection uses template literals (backticks) and ${testrailId} interpolation (e.g., const testrailId = "C4440539"; + pm.test(`${testrailId} …`)), which results in generated docs containing literal ${testrailId} strings and missing TestRail links. Consider expanding parsing to handle backtick strings and, when ${testrailId} is used, extracting the testrailId constant from the same script block so the correct C####### link can be emitted.

[Copilot]

extract_github_refs() only recognizes NASA-PDS/<repo>#<num> patterns. The collection also contains issue references in other common forms (e.g. NASA-PDS/registry-api/issues/66, and NASA-PDS/registry-api/#638), which are currently not converted into hyperlinks in the generated Markdown. Expanding the regex and link rendering to cover these variants would better meet the “GitHub issue references as hyperlinks” requirement.

Suggested change

	"""Extract GitHub issue refs like NASA-PDS/registry-api#494 from a string."""
	return re.findall(r"NASA-PDS/[\w-]+#\d+", name)
	"""Extract GitHub issue refs and normalize them to NASA-PDS/<repo>#<num>."""
	pattern = re.compile(
	r"(NASA-PDS/([\w-]+)(?:#(\d+)|/#(\d+)|/issues/(\d+)))"
	)
	refs = []
	for match in pattern.finditer(name):
	repo = match.group(2)
	issue_number = match.group(3) or match.group(4) or match.group(5)
	refs.append(f"NASA-PDS/{repo}#{issue_number}")
	return refs

[Copilot]

_build_anchor() attempts to mimic GitHub’s duplicate-heading anchor scheme, but it starts suffixing duplicates at -2. GitHub generates #heading, then #heading-1, #heading-2, etc. If duplicate headings ever occur in the collection, the TOC links produced here will not match GitHub’s rendered anchors. Adjust the suffixing to start at 1 for the first duplicate to keep TOC links reliable.

[tloubrieu-jpl]

Thanks @jordanpadams , that will help Catherine for the I&T