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

Fix automatically generated documentation for forc commands and plugins #6792

Open
ironcev opened this issue Dec 17, 2024 · 0 comments
Open
Labels
bug Something isn't working documentation

Comments

@ironcev
Copy link
Member

ironcev commented Dec 17, 2024

The mdbook-forc-documenter plugin for mdbook is not compatible with the output of the newest version of clap, which it parses in a simple manner to generate documentation pages for forc commands and plugins.

Below are some of the issues. All of them can be seen on the official documentation page of the current Sway version:
https://fuellabs.github.io/sway/v0.66.5/book/

The proposal is to also add a check to mdbook-forc-documenter to ensure that the version of clap didn't change. In case of a change, we would manually check the validity of the output and adapt the mdbook-forc-documenter's unit tests. Note that the documenter has unit tests, but they are all testing proper text transformations during rendering, which assumes that the input is in a certain format, which can potentially change when the clap version changes.

All the tools have the name "Forc"

E.g.:
forc-crypto
forc-debug

Subcommands are not recognized and generated as a single text

E.g.:
forc-crypto subcommands

Short text for examples is rendered as Heading 1

E.g.:
forc-crypto example

@ironcev ironcev added bug Something isn't working documentation labels Dec 17, 2024
@ironcev ironcev mentioned this issue Dec 17, 2024
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working documentation
Projects
None yet
Development

No branches or pull requests

1 participant