Document the event and alert type hierarchy #2297
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Because: - The event/alert hierarchy is only defined in the database, but the initial schema-defining SQL scripts. - To get this information into human-redable Sphinx docs, the best strategy seems to be extracting the data from a running database and generate a reStructured Text document for Sphinx to consume when building the docs.
Because: - It's easier to run the generator from a working dev environment, such as inside a docker container, than it is to use tox to set up a full integration environment just to extract data from the database.
Test results 6 files 6 suites 7m 52s ⏱️ Results for commit f20317f. |
hmpf
approved these changes
Sep 8, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The only complete "documentation" of NAV's event and alert type hierarchy exists in the SQL schema definitions (and this once-generated Wiki page ).
This information needs to be out there in the Sphinx-based user documentation, as part of the reference material. The simplest way to get it there is to just generate this documentation source text as necessary, when the event and alert type hierarchy changes (which is a rare event).
This PR sets out to do that.
A more viable solution for the future might be to actually define the hierarchy as Python code and use that to both seed the initial SQL database and to generate documentation. Why? Because the generator introduced in this PR needs access to an operational PostgreSQL database with the NAV schema - which usually requires a fully integrated NAV environment.