Skip to content

Document structured SIST results - #95

Merged
harryswift01 merged 2 commits into
mainfrom
22-docs-document-structured-sist-results
Nov 17, 2026
Merged

harryswift01 merged 2 commits into
mainfrom
22-docs-document-structured-sist-results

Conversation

@harryswift01

@harryswift01 harryswift01 commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR adds a Structured Results page to the docs, explaining how to write a result with sist --json, how to validate it, what it contains and how it relates to the text output. It also adds --json to the user guide. Closes #22.

Changes

  • Add docs/source/result-format.rst and link it from the index as "Structured Results".
  • Explain how to write a result with --json, alone or alongside -o.
  • Link the schema and every example result for download, with the commands used to make them.
  • Explain how to validate a result with sist-validate or ResultValidator, and what the cross-checks add beyond the schema.
  • Describe each section of a result, and the conventions for transitions, pairwise probabilities, positions, units, numbers and missing values.
  • Describe provenance and why comparisons should leave it out.
  • List the warning and error codes SIST raises, and how failed runs are written.
  • Explain the versioning rules.
  • Map each value in the text output to its place in the result, and list the values only the JSON result has.
  • Add --json to the options table and output section of the user guide.

Testing

  • The docs build passes with warnings treated as errors, and every download link resolves.

Impact

  • Documentation only. No change to code or output.

Checklist

  • Tests added or updated
  • Documentation updated
  • If dependencies in pyproject.toml changed, the lower bounds were reviewed deliberately

@harryswift01 harryswift01 self-assigned this Nov 9, 2026
@harryswift01 harryswift01 added the documentation Improvements or additions to documentation label Nov 9, 2026
@harryswift01 harryswift01 linked an issue Nov 9, 2026 that may be closed by this pull request
5 tasks
@harryswift01
harryswift01 changed the base branch from main to 96-feature-write-structured-json-results-from-sist November 12, 2026 15:14
@harryswift01
harryswift01 added this pull request to stack #99 November 12, 2026 15:14
@harryswift01
harryswift01 force-pushed the 22-docs-document-structured-sist-results branch from e7f9b70 to 85c1d29 Compare November 12, 2026 15:54
Base automatically changed from 96-feature-write-structured-json-results-from-sist to main November 16, 2026 15:42
@harryswift01
harryswift01 force-pushed the 22-docs-document-structured-sist-results branch from 85c1d29 to 895e73c Compare November 16, 2026 16:32

@jimboid jimboid left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A comprehensive documentation of the recently added features for data export. Happy to see this merge.

@harryswift01
harryswift01 merged commit 0d7391a into main Nov 17, 2026
20 checks passed
@harryswift01
harryswift01 deleted the 22-docs-document-structured-sist-results branch November 17, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs]: Document structured SIST results

2 participants