Add groups to command reference #4860
Draft
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.
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
Drop `ENABLE_SOURCE_LOCATION` flag.
Use `string::find_last_of()` instead. Not sure how this works on windows, but it was already using '/' so at least it's not any worse.
Also add comments to `help()` and `formatted_help()` to clarify usage.
Display subheadings for each command. Remove now redundant toc entry for `yosys> help <cmd>` line.
Content is now added to the `ContentListing` rather than the `PrettyHelp`. `open_*` methods return the `ContentListing` that was added instead of leaving a hanging continuation. This allows for (e.g.) options to be added directly to optiongroups, instead of requiring that groups be closed before continuation. This also means that all `PrettyHelp`s are a listing, with the actual log being called by the default `Pass::help()`; making the mode field redundant. Added `PrettyHelp::log_help()` which replaces the `PrettyHelp::Mode::LOG` logic. Added `ContentListing::back()` which just returns the last element of the underlying content vector. Some of the content tracking was made redundant and removed, in particular `PrettyHelp::_current_listing` and `ContentListing::parent`. Converted `ContentListing` to a class instead of a struct, adjusting constructors to match. Added `ContentListing` constructor that accepts a `source_location`. Update `HelpPass::dump_cmds_json()` for new log_help.
Update experimental pass warnings to use a shared function. Reduces repetition, and also allows all of the warning flags to be combined (which at present is just experimental and the new internal). Update `test_*` passes to call `internal()` in their constructors.
Commands flagged as internal will display a warning, just like experimental commands. Drop `passes/tests` group in favour of `internal` group, which is automatically assigned for any command without an assigned group which is flagged as internal.
Calling :cmd:title:`<cmd>` will generate a cross reference to `<cmd>`, but unlike :cmd:ref: which displays a literal block and puts the title (short_help) in the hovertext (the title field of an a-ref), :cmd:title: will display "<cmd> - <short_help>" as plain text. Thus replacing the previous use case of referring to :doc:`cmd/<cmd>`. Also refactor util py scripts to have more descriptive names.
KrystalDelusion
force-pushed
the
docs-preview-cmdref_groups
branch
from
b4559ca to
dc85360
Compare
|
Rebased to latest main (v |
readthedocs detection should only trigger on actual readthedocs builds.
Keep techlibs folder hierarchy. techlibs/* and passes/* groups are now nested under index_techlibs and index_passes respectively, with most (all?) of the passes/* pages getting proper headings, as well as backends/frontends/kernel. `index_passes_techmap` also references `index_techlibs`. Split command reference toc in twain, one with maxdepth=2 and one with maxdepth=3, since passes and techlibs now have an extra level of nesting. Move the `cmd_ref` link to the command reference, instead of top of the page. Remove `index_internal` and `index_other` from the toc, and mark the pages as orphan. Internal commands get a note callout after the command reference toc (although this doesn't work for the pdf build), while other commands are linked in the warning for missing `source_location` (since that *should* be the only time when there are any commands in the "unknown" group). Update autodoc extension versions, and mark the directives extension as not `parallel_read_safe` (it might be, but I'm not sure about how the xref lookups work if it is parallel so better to be safe).
Give formal index a proper title. Use `Pass::formatted_help()` to assign the group, but still return `false` because the help text still comes from `Pass::help()`. Tidy up some of the affected files' includes to make use of the shared `yosys.h` includes.
Need to copy parent class `option_spec` to retain default options (e.g. `:noindex:`).
Adds `autocmd_rst` directive, which effectively calls `autocmd` for the same command, but wraps it in a code-block in order to render the raw RST generated.
Use `chformal` as example, comparing the `autocmd` output with `ChformalPass::formal_help()`, the json dump from the `ContentListing`, the command line output, and the RST generated (using `autocmd_rst`). Includes bullet points on each step for more information. Should eventually end up in `yosys_internals/extending_yosys/contributing.rst`, but it currently lives in `cmd/index_internal.rst` to avoid merge conflicts since cell help documentation is still WIP. Also exports chformal source and help output to `docs/source/generated` during `make docs/prep`.
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