Docs/predicate documentation

[ccamel]

This PR addresses the generation of the documentation related to the prolog predicates implemented in the logic module.

Summary by CodeRabbit

• New Feature: Introduced a new command-line interface (CLI) tool for generating project documentation, enhancing the project's maintainability and ease of understanding.
• Documentation: Added comprehensive documentation for several predicates related to banking, address conversion, block information, DID components, hexadecimal encoding, JSON conversion, stream handling, string reading, SHA hashing, source file retrieval, and URI encoding. This will help users understand the functionality and usage of these predicates better.
• Refactor: Updated the Bech32Address, BlockHeight, BlockTime, ChainID, SHAHash, HexBytes, did_components/2, Open, JSONProlog, ReadString, and URIEncoded functions for better clarity and understanding.
• Style: Reordered and grouped import statements in several files for better code organization.
• Chore: Automated the generation of predicate documentation and integrated it into the GitHub workflow, improving the project's documentation process.

[coderabbitai]

Walkthrough

This pull request introduces significant enhancements to the documentation generation process, including new templates and scripts for generating markdown documentation for commands and predicates. It also includes updates to function signatures and comments in the codebase, improving clarity and readability. The changes are spread across various files, including GitHub workflows, Makefile, Go scripts, and several Go source files.

Changes

File(s)	Summary
.github/workflows/*.yml	Added steps to generate and update predicate documentation.
Makefile	Added new targets for generating documentation and updated existing ones.
docs/command/*.md	Updated default values and added new predicate documentation.
scripts/*.go	Introduced new functions for generating command and predicate documentation.
scripts/templates/*.gotxt	Added new templates for generating different types of content blocks.
starship/tests/*.go	Reordered import statements.
x/logic/predicate/*.go	Updated function signatures, comments, and examples for clarity.
x/logic/testutil/*.go, x/mint/testutil/*.go, x/vesting/testutil/*.go	Updated import statements.

🐇
"In the land of code, where logic is king,
Documentation is the song that we sing.
With each function and command, we now take a stand,
To make our codebase a well-understood land. 🎵🎶"

---

Tips

Chat with CodeRabbit Bot (@coderabbitai)

• If you reply to a review comment from CodeRabbit, the bot will automatically respond.
• To engage with CodeRabbit bot directly around the specific lines of code in the PR, mention @coderabbitai in your review comment
• Note: Review comments are made on code diffs or files, not on the PR overview.
• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai help to get help.

Note: For conversation with the bot, please use the review comments on code diffs or files.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.json

[coderabbitai]

Review Status

Actionable comments generated: 2
Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 14c0114 and b8f2af4.

Files ignored due to filter (7)

• go.mod
• go.sum
• x/logic/migrations/v2/types/genesis.pb.go
• x/logic/migrations/v2/types/params.pb.go
• x/logic/migrations/v2/types/query.pb.go
• x/logic/migrations/v2/types/tx.pb.go
• x/logic/migrations/v2/types/types.pb.go

Files selected for processing (28)

• .github/workflows/lint.yml (1 hunks)
• .github/workflows/update-draft-docs.yml (1 hunks)
• Makefile (3 hunks)
• docs/command/okp4d_tx_gov_submit-legacy-proposal_software-upgrade.md (1 hunks)
• docs/predicate/predicates.md (1 hunks)
• scripts/generate_command_doc.go (1 hunks)
• scripts/generate_predicates_doc.go (1 hunks)
• scripts/main.go (1 hunks)
• scripts/templates/doc.gotxt (1 hunks)
• scripts/templates/func.gotxt (1 hunks)
• scripts/templates/list.gotxt (1 hunks)
• scripts/templates/package.gotxt (1 hunks)
• scripts/templates/text.gotxt (1 hunks)
• starship/tests/setup_test.go (1 hunks)
• starship/tests/suite.go (1 hunks)
• x/logic/predicate/address.go (1 hunks)
• x/logic/predicate/bank.go (3 hunks)
• x/logic/predicate/block.go (2 hunks)
• x/logic/predicate/chain.go (1 hunks)
• x/logic/predicate/crypto.go (2 hunks)
• x/logic/predicate/did.go (1 hunks)
• x/logic/predicate/file.go (2 hunks)
• x/logic/predicate/json.go (1 hunks)
• x/logic/predicate/string.go (1 hunks)
• x/logic/predicate/uri.go (1 hunks)
• x/logic/testutil/expected_keepers_mocks.go (1 hunks)
• x/mint/testutil/expected_keepers_mocks.go (1 hunks)
• x/vesting/testutil/expected_keepers_mocks.go (1 hunks)

Files skipped from review due to trivial changes (20)

• docs/command/okp4d_tx_gov_submit-legacy-proposal_software-upgrade.md
• docs/predicate/predicates.md
• scripts/generate_predicates_doc.go
• scripts/templates/doc.gotxt
• scripts/templates/func.gotxt
• scripts/templates/list.gotxt
• scripts/templates/package.gotxt
• scripts/templates/text.gotxt
• starship/tests/setup_test.go
• starship/tests/suite.go
• x/logic/predicate/address.go
• x/logic/predicate/bank.go
• x/logic/predicate/block.go
• x/logic/predicate/chain.go
• x/logic/predicate/json.go
• x/logic/predicate/string.go
• x/logic/predicate/uri.go
• x/logic/testutil/expected_keepers_mocks.go
• x/mint/testutil/expected_keepers_mocks.go
• x/vesting/testutil/expected_keepers_mocks.go

Additional comments: 17

x/logic/predicate/did.go (1)

• 19-37: The updated comments provide a more detailed explanation of the DIDComponents function, its parameters, and its usage. The changes include specifying the type of DID as an Atom and providing more detailed descriptions of the Components term and its constituents. The examples have been updated to reflect these changes. The changes improve the clarity and completeness of the documentation.

.github/workflows/lint.yml (2)

• 211-213: The new step added to the workflow for generating predicate documentation seems to be in line with the existing structure and practices. However, ensure that the make doc-predicate command is correctly defined in the Makefile and it generates the expected documentation.

• 214-214: The check for Git diff in generated files has been moved down after the new step for generating predicate documentation. This is a good practice as it ensures that any changes made by the new step are also included in the Git diff check.

scripts/main.go (4)

• 1-10: The import statements are well organized and only necessary packages are imported. The cobra package is used for creating powerful modern CLI applications, and server from cosmos-sdk is used for handling server errors. Good use of packages for the intended functionality.

• 12-34: The main function is well structured. It creates a root command with two subcommands for generating command and predicate documentation. Error handling is done properly, with specific exit codes for server.ErrorCode errors and a default exit code for other errors.

• 36-45: The generateCommandDocumentationCommand function creates a cobra.Command for generating command documentation. It uses the GenerateCommandDocumentation function to perform the actual generation. This is a good example of separation of concerns.

• 47-56: The generatePredicateDocumentationCommand function creates a cobra.Command for generating predicate documentation. It uses the GeneratePredicateDocumentation function to perform the actual generation. This is a good example of separation of concerns.

x/logic/predicate/file.go (2)

• 13-22: The documentation for the SourceFile function has been enhanced with a more detailed explanation of the function's purpose, signature, and usage. The changes are clear and provide a better understanding of the function's role and how to use it.

• 90-107: The documentation for the Open function has been significantly improved. The new comments provide a detailed explanation of the function's purpose, signature, and usage. The changes are clear and provide a better understanding of the function's role and how to use it.

x/logic/predicate/crypto.go (2)

• 15-29: The updated comments for the SHAHash function provide a more detailed explanation of the function's purpose, usage, and limitations. The changes are primarily cosmetic and do not affect the function's implementation or behavior. The changes improve the readability and understandability of the code.

• 46-59: The updated comments for the HexBytes function provide a more detailed explanation of the function's purpose and usage. The changes are primarily cosmetic and do not affect the function's implementation or behavior. The changes improve the readability and understandability of the code.

scripts/generate_command_doc.go (1)

• 11-25: The function GenerateCommandDocumentation has been refactored from the previous main function and generateDocumentation function. The error handling and logging that was previously in the main function is now expected to be handled by the caller of GenerateCommandDocumentation. Ensure that the caller is properly handling any errors returned by this function.

.github/workflows/update-draft-docs.yml (1)

• 47-63: The new hunk introduces a step to update the predicates documentation repository. It uses the fjogeleit/http-request-action action to send an HTTP POST request to the GitHub API. The request is made to the URL https://api.github.com/repos/okp4/docs/actions/workflows/39152549/dispatches and includes a custom header with an authorization token. The request payload is a JSON object containing various inputs such as the repository, section, docs directory, and draft status. This step is responsible for updating the predicates documentation repository. Ensure that the workflow in the predicates documentation repository is set up to handle these requests correctly. Also, verify that the OKP4_TOKEN secret is set up in the GitHub secrets for this repository.

Makefile (4)

• 353-353: The doc target in the Makefile has been updated to include doc-predicate in addition to doc-proto and doc-command. This means that when the doc target is run, it will now also generate documentation for the predicates in the logic module. Ensure that this is the intended behavior and that the necessary resources for generating predicate documentation are available.

• 384-387: The doc-command target has been updated. The script to generate the command documentation is now run from the root directory instead of the docs directory. Also, the script is now run with the argument command. Ensure that the script can be run from the root directory and that it correctly handles the command argument.

-    @cd docs; \
-    go run ../scripts/generate_command_doc.go; \
+    @OUT_FOLDER="docs/command"; \
+    go get ./scripts; \
+    go run ./scripts/. command; \

• 396-396: The doc-command target now specifies a configuration file for markdownlint. Ensure that this file exists and contains the correct configuration for linting the generated command documentation.

-    ${DOCKER_IMAGE_MARKDOWNLINT} -f $$OUT_FOLDER
+    ${DOCKER_IMAGE_MARKDOWNLINT} -f $$OUT_FOLDER -c docs/.markdownlint.yaml

• 398-410: A new doc-predicate target has been added to the Makefile. This target generates markdown documentation for all the predicates in the logic module. It creates a new directory docs/predicate, runs a script to generate the documentation, and then lints the generated documentation using markdownlint. Ensure that the script correctly generates the predicate documentation and that the markdownlint configuration file is suitable for linting this documentation.

+ .PHONY: doc-predicate
+ doc-predicate: ## Generate markdown documentation for all the predicates (module logic)
+     @echo "${COLOR_CYAN} 📖 Generate markdown documentation for the predicates${COLOR_RESET}"
+     @OUT_FOLDER="docs/predicate"; \
+     rm -rf $$OUT_FOLDER; \
+     mkdir -p $$OUT_FOLDER; \
+     go get ./scripts; \
+     go run ./scripts/. predicate; \
+     docker run --rm \
+       -v `pwd`:/usr/src/docs \
+       -w /usr/src/docs \
+       ${DOCKER_IMAGE_MARKDOWNLINT} -f $$OUT_FOLDER -c docs/.markdownlint.yaml

[amimart]

Awesome! Thx 🙏