Skip to content

Feat: extend documentation tool for subcommand configurations #2455

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 10 commits into from
May 5, 2025
Merged

Feat: extend documentation tool for subcommand configurations #2455

merged 10 commits into from
May 5, 2025

Conversation

dlachaume
Copy link
Collaborator

@dlachaume dlachaume commented Apr 30, 2025 •
edited
Loading

Content

This PR includes enhancements to the documentation tool, enabling it to support subcommand configurations.

Pre-submit checklist

  • Branch
    • Tests are provided (if possible)
    • Crates versions are updated (if relevant)
    • CHANGELOG file is updated (if relevant)
    • Commit sequence broadly makes sense
    • Key commits have useful messages
  • PR
    • All check jobs of the CI have succeeded
    • Self-reviewed the diff
    • Useful pull request description
    • Reviewer requested
  • Documentation
    • Update README file (if relevant)
    • Update documentation website (if relevant)
    • Add dev blog post (if relevant)
    • Add ADR blog post or Dev ADR entry (if relevant)
    • No new TODOs introduced

Comments

Additionally, an assessment of the differences between the documentation generated by mithril-doc and the currently published website documentation has been completed. The identified differences are as follows:

  • Default configuration discrepancies: There are mismatches between the default configuration structure and the serve command configuration structure (fields are not exactly the same). In addition, default configuration details for subcommands are missing. The mithril-doc merge mechanism for default configurations may need improvement.
  • Environment variable representation: The generated documentation does not take into account environment variables for configuration structures such as protocol_parameters and cardano_transactions_signing_config, which use double underscores (__) as separators.
  • Line breaks in clap command output: The generated documentation handles line breaks differently from the website documentation.
  • Markdown formatting: The generated Markdown differs from the website version, which is formatted with prettier.
  • Order of command sections: The sequence of command sections in the generated documentation does not match the one on the website.
  • --help command entries: Each subcommand table includes a help command entry, which may be unnecessary.

Issue(s)

Closes #2450

@dlachaume dlachaume self-assigned this Apr 30, 2025
@github-actions GitHub Actions
Copy link

github-actions bot commented Apr 30, 2025 •
edited
Loading

Test Results

    3 files  ± 0     57 suites  ±0   11m 55s ⏱️ -4s
1 891 tests +10  1 891 ✅ +10  0 💤 ±0  0 ❌ ±0 
2 355 runs  +10  2 355 ✅ +10  0 💤 ±0  0 ❌ ±0 

Results for commit eaea965. ± Comparison against base commit e4955a4.

♻️ This comment has been updated with latest results.

@dlachaume dlachaume temporarily deployed to testing-preview April 30, 2025 15:59 — with GitHub Actions Inactive
@dlachaume dlachaume force-pushed the ensemble/2384/extend-documentation-tool-for-subcommand-configurations branch from c25bc04 to 56e27e2 Compare April 30, 2025 16:01
@dlachaume dlachaume temporarily deployed to testing-preview April 30, 2025 16:20 — with GitHub Actions Inactive
@dlachaume dlachaume force-pushed the ensemble/2384/extend-documentation-tool-for-subcommand-configurations branch from 56e27e2 to aa2f904 Compare May 2, 2025 09:15
@dlachaume dlachaume temporarily deployed to testing-preview May 2, 2025 09:36 — with GitHub Actions Inactive
@dlachaume dlachaume marked this pull request as ready for review May 2, 2025 09:47
@dlachaume dlachaume requested a review from sfauvel May 2, 2025 09:47
@dlachaume dlachaume force-pushed the ensemble/2384/extend-documentation-tool-for-subcommand-configurations branch from a82b4b8 to 21cc517 Compare May 2, 2025 13:37
sfauvel
sfauvel approved these changes May 2, 2025
View reviewed changes
Copy link
Collaborator

@sfauvel sfauvel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@dlachaume dlachaume temporarily deployed to testing-preview May 2, 2025 13:55 — with GitHub Actions Inactive
@dlachaume dlachaume force-pushed the ensemble/2384/extend-documentation-tool-for-subcommand-configurations branch 2 times, most recently from fceaf6a to 11353cf Compare May 2, 2025 14:46
@dlachaume dlachaume temporarily deployed to testing-preview May 2, 2025 15:05 — with GitHub Actions Inactive
@dlachaume dlachaume requested review from jpraynaud and turmelclem May 2, 2025 15:07
turmelclem
turmelclem approved these changes May 5, 2025
View reviewed changes
Copy link
Collaborator

@turmelclem turmelclem left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

dlachaume and others added 10 commits May 5, 2025 17:53
@dlachaume @sfauvel
feat(doc): start reworking mithril-doc to support specific subcomma…
165b329 
…nds configurations

Co-authored-by: Sébastien Fauvel <sfauvel@users.noreply.github.com>
@sfauvel @dlachaume
refactor(doc): update mithril-doc to improve get_field function
28a0e79
@sfauvel @dlachaume
feat(common): add a macro assert_equivalent_macro to identify caller …
afee967 
…when it fails
@dlachaume @turmelclem
feat(doc): use the configurations map to produce the documentation of…
ab753ad 
… the commands

Co-authored-by: Clément TURMEL <turmelclem@users.noreply.github.com>
@dlachaume @sfauvel @turmelclem
feat(aggregator): adapt the aggregator for the subcommands configurat…
ceebb9f 
…ions documentation

Co-authored-by: Sébastien Fauvel <sfauvel@users.noreply.github.com>
Co-authored-by: Clément TURMEL <turmelclem@users.noreply.github.com>
@dlachaume
refactor(signer): make signer use new function to generate the docume…
70d7025 
…ntation with configurations
@dlachaume
refactor(doc+signer+aggregator): remove unused original `execute_with…
15f6bb3 
…_configurations` in favor of newer version
@dlachaume @sfauvel
feat(doc): handle optional configuration field
32e11f6 
Co-authored-by: Sébastien Fauvel <sfauvel@users.noreply.github.com>
@dlachaume
fix(doc): keep fields order when merging struct docs
ceee8d5 
delegate field merging responsibility to `FieldDoc`
@dlachaume
chore: upgrade crate versions
eaea965 
* mithril-doc-derive from `0.1.17` to `0.1.18`
* mithril-doc from `0.1.22` to `0.1.23`
* mithril-aggregator from `0.7.46` to `0.7.47`
* mithril-common from `0.5.27` to `0.5.28`
* mithril-signer from `0.2.244` to `0.2.245`
@dlachaume dlachaume force-pushed the ensemble/2384/extend-documentation-tool-for-subcommand-configurations branch from 11353cf to eaea965 Compare May 5, 2025 15:54
@dlachaume dlachaume temporarily deployed to testing-preview May 5, 2025 16:03 — with GitHub Actions Inactive
@dlachaume dlachaume merged commit 4d5000a into main May 5, 2025
39 checks passed
@dlachaume dlachaume deleted the ensemble/2384/extend-documentation-tool-for-subcommand-configurations branch May 5, 2025 16:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@sfauvel sfauvel sfauvel approved these changes

@jpraynaud jpraynaud jpraynaud approved these changes

@turmelclem turmelclem turmelclem approved these changes

Assignees

@dlachaume dlachaume

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Fix aggregator commands automatic documentation
4 participants
@dlachaume @sfauvel @jpraynaud @turmelclem