Add groups to command reference #4860
Draft
+1,355
−247
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
The `help -write-rst-cells-manual` approach was made redundant by `help -dump-cells-json`.
Using `{begin|end}_object` inserts curly braces instead of square brackets, which can result in reordering (and may be syntactically incorrect?).
Experimental new formatting for describing passes that can be rendered into the standard help format, as well as being more amenable to smarter formatting for web documentation.
Add `doc_string` field to `Pass` constructor Add `docs/util/newcmdref.py` to contain command domain Update `docs/util/cmdref.py` with `cmd:usage` and `cmd:optiongroup` for describing commands. Functional, but WIP.
Fix `help $cell` type references, as well as actually implement the fallback to yoscrypt.
Easier to test
Define `PrettyHelp` class with methods for declaring different parts of help message. Currently able to produce standard help messages as expected. Updates chformal to use (only) the new help_v2. Currently makes use of a global static to track the current help context, allowing register.h to live in blissful ignorance and instead rely on help_v2 implementations calling `auto *help = PrettyHelp::get_current();` and `return true;` to minimise impact on rebuilds (i.e. not requiring every source file to be recompiled).
Refactor `PrettyHelp::endgroup()` -> `PrettyHelp::close(int levels = 1)`.
Use `std::experimental::source_location` because clang support is `??` Add `ENABLE_SOURCE_LOCATION` make variable and corresponding `YOSYS_ENABLE_SOURCE_LOCATION` define. Dummy out the struct if disabled and check for null instead of using `#ifdef` blocks everywhere.
Current modes are `LOG` and `LISTING`, which `log()` and store for conversion to json respectively. Add `ContentListing` listing struct to (recursively) contain help data for conversion to a json object to be exported and used elsewhere (e.g. the docs). Rather than formatting as rst we can just export with type information and do the conversion at the destination (i.e. in the python code which loads the domain for autodoc). Implement `PrettyHelp::has_content()`. Provide `PrettyHelp::get_content()` which returns a read-only list of the current content. `PrettyHelp` constructor takes optional `Mode` enum to define format of help content. Updates `PrettyHelp` methods to use a switch case for checking current mode, calling `log_abort()` in the default case (i.e. unsupported mode).
Compatible with `dump_cmds_json`.
Formatting is nicer when there is only one code block instead of multiple in a row, especially in pdf.
Assign root location in call to `PrettyHelp::get_current()`. Set default `source_file` to `"unknown"`, since that appears to be the default value rather than `nullptr`.
Also adds note on source location if available.
- Command list for script passes - Check buffer after loop - Close options properly - Ignore mismatched sigs e.g. `fsm_detect` on `fsm` - Require double blank line before new signature
Removes group parsing from command ref domain, instead relying on a 'groups' object in the cmds.json file. `docs/source/cmd` is no longer ignored or cleaned.
Revert `PrettyHelp::get_current()` for no args since we can use `Pass::location` instead.
Sets `chformal` group to "formal" for testing purposes
Also output `pass->location.{file_name,line,function_name}()`.
If no group is given (i.e. it is "unknown"), attempt to automatically apply a group.
If we have source locations, this is based on path to the source file.
If we do not have source locations, try to match on the pass name instead.
Log an info message, and put a warning for the content instead.
Changes a bunch of :doc:`/cmd/*` to :cmd:ref:`*` with the intention of changing it later to something that replicates the previous effect of displaying the commands `short_help`.
i.e. we don't need to clean it, and we don't need to include it in the docs artifact
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.
What are the reasons/motivation for this change?
The cmdref is currently just a big list of all commands and can be a bit difficult to navigate.
Explain how this is achieved.
Refactor cmds to follow cells pattern (i.e. export to json and import with autodoc).
Group commands based on path, with fallback to name if path is not available (since it requires
source_location).If applicable, please suggest to reviewers how they can test the change.
Preview build