Skip to content
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

Tool to auto populate documentation examples for decision point objects #370

Conversation

ahouseholder
Copy link
Contributor

This PR adds doctools.py, which does the following:

  • Loads existing SSVC decision points
  • For each version of each decision point:
    • Emit the decision point as a json file
    • Emit a markdown blob that can be used as an include in the documentation
    • Create a soft link to the decision point name for the most recent version thereof (to make it easier to generate updates)

Also included:

  • The content generated by the above
  • Edits to the decision point markdown files to include the generated content
  • A relatively unrelated change to reorganize the ssvc.dp_groups module for future maintenance convenience.

This PR is the final chunk of what was in PR #339. Note that when you look at the file-level changes, it appears as if a lot has changed. However, I attempted to break up those changes in the commits as follows:

  • 4d5a4a4 reorganizes ssvc.dp_groups

  • 90c736b is the doctools.py script all by itself

  • 2aa8c39 has the content that doctools.py emits

  • 2c7bd87 adds a few decision points that we had previously not included in the reference section (virulence, utility, human impact, public safety impact). The accompanying docs include links between the various constituent elements for the compound ones. The page for virulence notes that it is superseded by automatable.

  • 3809a83 modifies existing docs to include the generated content. Note that for decision points having multiple extant versions, there is now a previous version section at the bottom of the page so folks can see what the older versions looked like

  • resolves Create tool to auto-populate documentation examples for decision point objects #364

- It was broken before (values were not getting created as objects)
- Make the _Commented a mixin class, but remove it from the base
class anyway. We don't really need it yet.
- Simplify the decision point registry
- fix up unit tests
Copy link
Collaborator

@j--- j--- left a comment

Choose a reason for hiding this comment

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

There are a couple implications in here that I'd like to discuss before approving. The only one that I'd consider as truly blocking is the naming of Virulence as a 1.0 metric. By blocking, I mean I want to resolve that discussion before we commit this PR. Not sure which way it will be resolved.

docs/_generated/decision_points/safety_impact_1_0_0.md looks less good than the original PDF, because the table there was structured very differently than the other decision points. It has these sub-categories of physical harm, psychological harm, etc. And I think these are, predictably, printing in a way that is confusing.

I propose we make a new issue to attempt a re-write of the safety impact decision point to make the text more amenable to being consistent with our more automated design and document management process. The code here does what is expected given the text for safety impact. So it's not a problem with this PR.

I think the question about whether compound decision points are named and stored differently to keep them separate can also be a new issue that we can discuss separately and modify things later if we decide to do that.

docs/_generated/decision_points/safety_impact_1_0_0.md Outdated Show resolved Hide resolved
data/json/decision_points/virulence_1_0_0.json Outdated Show resolved Hide resolved
data/json/decision_points/utility_1_0_1.json Show resolved Hide resolved
docs/reference/decision_points/virulence.md Outdated Show resolved Hide resolved
mkdocs.yml Outdated Show resolved Hide resolved
ahouseholder and others added 2 commits November 9, 2023 11:57
failing because bad merge
Copy link
Collaborator

@j--- j--- left a comment

Choose a reason for hiding this comment

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

All my comments have been addressed / opened as new issues to handle later. Thanks!

@ahouseholder ahouseholder merged commit 0fecedf into main Nov 14, 2023
3 checks passed
@ahouseholder ahouseholder deleted the 364-create-tool-to-auto-populate-documentation-examples-for-decision-point-objects branch November 14, 2023 19:26
@ahouseholder ahouseholder added the tools Software Tools label Nov 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
tools Software Tools
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create tool to auto-populate documentation examples for decision point objects
2 participants