Skip to content

Autogenerate parts of scenarios/README.md #1436

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.

Sign up for GitHub

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

Jump to bottom
Closed
kostmo opened this issue Aug 21, 2023 · 0 comments · Fixed by #1441
Closed

Autogenerate parts of scenarios/README.md #1436

kostmo opened this issue Aug 21, 2023 · 0 comments · Fixed by #1441
Assignees
@kostmo
Labels
Z-Developer Experience This issue seeks to make life easier for developers writing Scenarios or other Swarm code. Z-Documentation This issue is about README or Wikis or Haddock or... Z-Feature A new feature to be added to the game.

Comments

@kostmo
Copy link
Member

kostmo commented Aug 21, 2023 •
edited
Loading

See #1432 (comment):

Much of the content of scenarios/README.md is identical to that in data/schema/entities.json. We should autogenerate the former from the latter, in whole or in part.

Builds upon #344.

Related: #1428, as the json schema must be parsed.
@kostmo kostmo added Z-Feature A new feature to be added to the game. Z-Documentation This issue is about README or Wikis or Haddock or... Z-Developer Experience This issue seeks to make life easier for developers writing Scenarios or other Swarm code. labels Aug 21, 2023
@kostmo kostmo self-assigned this Aug 21, 2023
This was referenced Aug 22, 2023
Closed
Merged
Merged
mergify bot pushed a commit that referenced this issue Aug 28, 2023
@kostmo
Validate scenarios against json schema (#1475)
bfc0c14 
Closes #1428

Since the authoritative validation of scenario files is actually performed by virtue of `swarm` parsing them, this CI job actually exists to ensure the JSON Schema descriptions are accurate.  This is important for two purposes:
* Documentation is generated from the JSON Schema files (#1436)
* JSON Schema has integration with VS Code and other IDEs

# Testing

Verified that the schema checker action does indeed work by intentionally pushing an invalid scenario file in f789f81.
@mergify mergify bot closed this as completed in #1441 Oct 9, 2023
mergify bot pushed a commit that referenced this issue Oct 9, 2023
@kostmo
Autogenerate scenario schema doc (#1441)
4e886e0 
Closes #1436.

The schema `.json` files are now the authoritative source of truth for documentation.

Wrote a very simple parser for JsonSchema to extract the documentation from JSON.

Split the README.md into [static](https://github.com/swarm-game/swarm/blob/c314cc50a1429c9c3405954a4ac43d6ad6d2f7f1/data/scenarios/README.md) and [auto-generated](https://github.com/swarm-game/swarm/blob/c314cc50a1429c9c3405954a4ac43d6ad6d2f7f1/data/scenarios/doc-fragments/SCHEMA.md) parts.

Added a custom `"footers"` key to schema files to support inclusion of other markdown files for each object description.

# Schema doc regeneration

    ./scripts/regenerate-schema-docs.sh
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@kostmo kostmo

Labels
Z-Developer Experience This issue seeks to make life easier for developers writing Scenarios or other Swarm code. Z-Documentation This issue is about README or Wikis or Haddock or... Z-Feature A new feature to be added to the game.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Autogenerate scenario schema doc swarm-game/swarm
1 participant
@kostmo