Add groups to command reference #4860
Open
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
KrystalDelusion
force-pushed
the
docs-preview-cmdref_groups
branch
from
b4559ca to
dc85360
Compare
|
Rebased to latest main (v |
KrystalDelusion
force-pushed
the
docs-preview-cmdref_groups
branch
from
448d9cc to
0c1a735
Compare
|
Rebased to latest main (v |
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
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.
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`.
Also tidy `#include`s.
Rename passes/cmds from "General passes" to "Design modification". More `yosys.h` includes. cmdref: Split passes/status from passes/cmds Rename passes/cmds from "General passes" to "Design modification". More `yosys.h` includes.
Add `options` map for setting `ContentListing` options with key:val pairs; currently only used with `ContentListing::codeblock()` language arg. Fix generated codeblock rst to print each line of code with indentation, and change it to use explicit an `code-block` so we can set a language on it.
Or at least all of the synth commands, because they have the same preceding text. Except `synth_fabulous`, because that has unconditional `read_verilog`s at the start. Which seems like a bad idea and and not compatible with `-run`?
Linking to optiongroups doesn't add *that* much, and is kind of a pain; meanwhile having the optiongroups adds an extra level of indentation. Instead of options needing to be in an option group, they instead go in either the root node or nested in a usage node. Putting them in a usage node allows for more-or-less the previous behaviour but without making it the default.
`formatted_help()` introduced the override keyword, which means that the other two methods that were marked as virtual instead raised a warning about inconsistent use of override. This fixes that by bringing the synthprop (more) in line with the rest of the code-base.
Also fixing some missing refs (using single backticks instead of double).
KrystalDelusion
force-pushed
the
docs-preview-cmdref_groups
branch
from
ba8155a to
7d7c32d
Compare
|
Rebased on latest main (v |
|
There's a huge amount of TODOs shown directly on the linked page, I guess that's not on purpose right? |
TODOs are normally hidden for published builds, but not previews or local builds. There might be a couple new TODOs added in this PR, but it shouldn't be anything blocking; I've taken to using |
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