docs(make): improve and centralize make help output

[loren-osborn]

Summary

This PR provides a minor quality-of-life improvement for new Gno developers by enhancing make help output across the project.

Highlights

• make help now displays inline comments appended to target lines, offering clear, one-line explanations for each Make target.
• make -C contribs help:
  • Expands wildcard subdirectories,
  • Includes their annotated make help outputs,
  • Extracts the first line of each README.md to display a brief description of each tool.
• Preserves the existing self-scraping help behavior—just with more context and clarity.

No functional changes—just improved discoverability and documentation for contributors.

[Gno2D2]

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):

• IGNORE the bot requirements for this PR (force green CI check)
• The pull request description provides enough details

Read More

🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.

✅ Automated Checks (for Contributors):

🟢 Maintainers must be able to edit this pull request (more info)
🟢 Pending initial approval by a review team member, or review from tech-staff

☑️ Contributor Actions:

1. Fix any issues flagged by automated checks.
2. Follow the Contributor Checklist to ensure your PR is ready for review.
   • Add new tests, or document why they are unnecessary.
   • Provide clear examples/screenshots, if necessary.
   • Update documentation, if required.
   • Ensure no breaking changes, or include BREAKING CHANGE notes.
   • Link related issues/PRs, where applicable.

☑️ Reviewer Actions:

1. Complete manual checks for the PR, including the guidelines and additional checks if applicable.

📚 Resources:

• Report a bug with the bot.
• View the bot’s configuration file.

Debug

Automated Checks

Maintainers must be able to edit this pull request (more info)

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 The pull request was created from a fork (head branch repo: loren-osborn/gno)

Then

🟢 Requirement satisfied
└── 🟢 Maintainer can modify this pull request

Pending initial approval by a review team member, or review from tech-staff

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 Not (🔴 Pull request author is a member of the team: tech-staff)

Then

🟢 Requirement satisfied
└── 🟢 If
    ├── 🟢 Condition
    │   └── 🟢 Or
    │       ├── 🔴 At least 1 user(s) of the organization reviewed the pull request (with state "APPROVED")
    │       ├── 🟢 At least 1 user(s) of the team tech-staff reviewed pull request
    │       └── 🔴 This pull request is a draft
    └── 🟢 Then
        └── 🟢 And
            ├── 🟢 Not (🔴 This label is applied to pull request: review/triage-pending)
            └── 🟢 At least 1 user(s) of the team tech-staff reviewed pull request

Manual Checks

**IGNORE** the bot requirements for this PR (force green CI check)

If

🟢 Condition met
└── 🟢 On every pull request

Can be checked by

• Any user with comment edit permission

The pull request description provides enough details

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 Not (🔴 Pull request author is a member of the team: core-contributors)
    └── 🟢 Not (🔴 Pull request author is user: dependabot[bot])

Can be checked by

• team core-contributors

[loren-osborn]

This is still an early proof of concept. I welcome feedback.

while I might have liked doxygen style comments for each target, this implementation is significantly less complex than would be required for multiple-line prefixed comment block parsing.

[loren-osborn]

FYI: work not yet finished:

comments should be added to all relevant targets

[moul]

The makefile looks too complex.
Not sure how much it can be useful, but it looks like something we should have in an external script or binary to keep the makefiles simple.

[loren-osborn]

The makefile looks too complex. Not sure how much it can be useful, but it looks like something we should have in an external script or binary to keep the makefiles simple.

You raise a valid point. I’ll admit I may be a bit too comfortable with complex Makefiles for my own good. I’ll likely finish this PR regardless—as a learning exercise—but I was hoping it might prove useful to others as well.

For the sake of discussion, here’s a side-by-side comparison of the output before and after this change, using the two directories I’ve completed so far:

Before:

% make
Available make commands:
  fmt
  help
  install
  install.gno
  install.gnodev
  install.gnokey
  lint
  test
  test.components
  tidy

 % make -C contribs
Available make commands:
  fmt
  help
  install
  install.%
  install_all
  lint
  lint.%
  test
  test.%
  tidy

 %

After:

% make
Available make commands:
  fmt               <-- Format components Tendermint2, GnoVM, Gno.land and examples
  help              <-- Print this help message
  install.gno       <-- Install Gno
  install.gnodev    <-- Install GnoDev
  install.gnokey    <-- Install GnoKey
  install           <-- Install GnoKey, Gno and GnoDev
  lint              <-- Lint all non-vendor *.go and *.gno code recursively
  test.components   <-- Test components Tendermint2, GnoVM, Gno.land, examples and misc
  test              <-- Test everything (for now, same as test.components)
  tidy              <-- Run 'go mod tidy' in all Go modules within the `misc` directory

Sub-directories with make targets:
    *   /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C docs
    *   /Applications/Xcode.app/Contents/Developer/usr/bin/make -C examples
    *   /Applications/Xcode.app/Contents/Developer/usr/bin/make -C gno.land
    *   /Applications/Xcode.app/Contents/Developer/usr/bin/make -C gnovm
    *   /Applications/Xcode.app/Contents/Developer/usr/bin/make -C misc
    *   /Applications/Xcode.app/Contents/Developer/usr/bin/make -C tm2

       * Is documented with a `help` target.
       
 % make -C contribs
Available make commands:
  fmt                   <-- Format all Go files in this directory and subdirectories
  help                  <-- Print this help message
  install               <-- Print instructions for installing one or all subpackages
  install.github-bot    <-- Install subpackage github-bot (GitHub Bot)
  install.gnodev        <-- Install subpackage gnodev (Your Gno Development Companion)
  install.gnofaucet     <-- Install subpackage gnofaucet (Start a local faucet)
  install.gnogenesis    <-- Install subpackage gnogenesis (CLI tool for managing the Gnoland blockchain's `genesis.json` file)
  install.gnohealth     <-- Install subpackage gnohealth (Gno Health Check CLI)
  install.gnokeykc      <-- Install subpackage gnokeykc (CLI tool enhancing gnokey for system keychain integration)
  install.gnomd         <-- Install subpackage gnomd (Terminal Markdown Viewer for Gno Documentation)
  install.gnomigrate    <-- Install subpackage gnomigrate (CLI Gno legacy data migration tool.)
  install_all           <-- Install all subpackages
  lint                  <-- Lint all subpackages
  lint.github-bot       <-- Lint subpackage github-bot (GitHub Bot)
  lint.gnodev           <-- Lint subpackage gnodev (Your Gno Development Companion)
  lint.gnofaucet        <-- Lint subpackage gnofaucet (Start a local faucet)
  lint.gnogenesis       <-- Lint subpackage gnogenesis (CLI tool for managing the Gnoland blockchain's `genesis.json` file)
  lint.gnohealth        <-- Lint subpackage gnohealth (Gno Health Check CLI)
  lint.gnokeykc         <-- Lint subpackage gnokeykc (CLI tool enhancing gnokey for system keychain integration)
  lint.gnomd            <-- Lint subpackage gnomd (Terminal Markdown Viewer for Gno Documentation)
  lint.gnomigrate       <-- Lint subpackage gnomigrate (CLI Gno legacy data migration tool.)
  test                  <-- Test all subpackages
  test.github-bot       <-- Test subpackage github-bot (GitHub Bot)
  test.gnodev           <-- Test subpackage gnodev (Your Gno Development Companion)
  test.gnofaucet        <-- Test subpackage gnofaucet (Start a local faucet)
  test.gnogenesis       <-- Test subpackage gnogenesis (CLI tool for managing the Gnoland blockchain's `genesis.json` file)
  test.gnohealth        <-- Test subpackage gnohealth (Gno Health Check CLI)
  test.gnokeykc         <-- Test subpackage gnokeykc (CLI tool enhancing gnokey for system keychain integration)
  test.gnomd            <-- Test subpackage gnomd (Terminal Markdown Viewer for Gno Documentation)
  test.gnomigrate       <-- Test subpackage gnomigrate (CLI Gno legacy data migration tool.)
  tidy                  <-- Run 'go mod tidy' in all Go modules within this directory and subdirectories

Sub-directories with make targets:
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/github-bot
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnodev
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnofaucet
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnogenesis
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnohealth
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnokeykc
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnomd
        /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnomigrate
        
 %

That said, this might be too much information for a new contributor at once.

@moul – I appreciate you taking a look. I agree this is more complex than ideal, and I’m still not convinced the value justifies the overhead. There’s also quite a bit of boilerplate here that could probably be factored out into a shared script to simplify the Makefiles.

Either way, I look forward to wrapping this up and turning my attention to a project with more lasting impact.

[loren-osborn]

Hi @moul,

I'm not sure if this is quite what you had in mind. The logic is essentially the same as before, but now centralized in misc/makeHelpMsgs.mk. While the result is only slightly more concise, it avoids repeating the same logic across seven different files—which I think is a worthwhile improvement.

It does introduce light use of Make functions, which might make it a bit harder to read at first glance, but in exchange, all of the comment scraping and formatting logic now lives in one place.

That said, if you feel this direction complicates things more than it helps, I’m happy to revisit or revert it.

Best regards,
@loren-osborn

P.S. I still have to add the applicable comments to: examples/Makefile, gno.land/Makefile, gnovm/Makefile, misc/Makefile and tm2/Makefile

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

📢 Thoughts on this report? Let us know!

[jefft0]

Hi @loren-osborn . Can you please fix the failed check for "PR Title Linter"?

[loren-osborn]

Hi @loren-osborn . Can you please fix the failed check for "PR Title Linter"?

Hi @jefft0 — thanks! I’ve updated the title to use docs, since this improves make help output and centralizes related logic.

If anyone feels it fits better under build, I’m happy to adjust.

[jefft0]

Hi @loren-osborn . The "PR Title Linter" is still unhappy. "WIP" is usually for a draft PR. Is the PR ready for review? If yes, then please remove "WIP". But if you are still working on it, then please convert to draft.

[loren-osborn]

Hi @loren-osborn . The "PR Title Linter" is still unhappy. "WIP" is usually for a draft PR. Is the PR ready for review? If yes, then please remove "WIP". But if you are still working on it, then please convert to draft.

Yes, while I'm close to done, it is still WIP... (I would rather mark this with a label, but I don't believe I have labeling permission)

[thehowl]

I marked it as a draft in the GitHub UI.

You should also be able to change it; you can find a link to "Convert to draft" on an issue sidebar, and you can then click "ready for review" in the merge box when it's ready.

[loren-osborn]

Thanks, @thehowl!

I believe the PR is now ready for review.

I wasn't able to find a "GitHub UI" application specifically, but I did install GitHub Desktop. From there, selecting the PR just opens it in the browser—but I did go ahead and mark it as "ready for review" from there.

Thanks again!

[thehowl]

Thanks for your contribution :)

I think this is in a good spirit; but there's a bit too much logic being written as make rules for my taste; I don't understand what's going on in makeHelpMsgs.mk, and I don't want to.

Can we make a makefile_help.sh script, which given an argument of a makefile, generates the desired help output?

I believe bash scripts are generally easier to read and maintain than makefile magic.

[thehowl]

use ```

[loren-osborn]

Good catch.

[loren-osborn]

I think this is in a good spirit; but there's a bit too much logic being written as make rules for my taste; I don't understand what's going on in makeHelpMsgs.mk, and I don't want to.

That makes sense—thanks for the feedback!

I’ll go ahead and move the logic into a makefile_help.sh script. The only part that really needs to stay in the Makefile is the -C detection, since it doesn’t work from a subprocess.

The .mk version was meant to be simple and usable, but a shell script is clearly the better long-term fit.

Can we make a makefile_help.sh script, which given an argument of a makefile, generates the desired help output?

To match the current behavior, I’ll pass in the Makefile, the -C context, and (in the case of contribs) a list of wildcard values. The script depends a bit on the current simplicity of the Makefiles—so it may break if they ever get too clever.

[loren-osborn]

@thehowl I have to head out shortly and still have quite a bit to do to get this production-ready, but I wanted to check if you’d be willing to take a quick look at misc/makefile_help.go and let me know if it’s along the lines of what you had in mind.

• I chose to implement this in Go (invoked with go run) since I think it’ll be much more maintainable than a bash script.
• It’s not yet hooked up to the Makefiles, so it’s not “live.”
• Many of the comments are outdated or incorrect—feel free to ignore them.
• I plan to refactor for clarity and add more test coverage.
• Mainly just looking to confirm whether the overall direction looks good to you.

I won’t mark this "ready for review" until it’s cleaned up—I’m just hoping to get some early feedback.

P.S. I'm available on Discord if you want to discuss this at all.

P.P.S. I’m not a huge fan of the flag package—particularly how I chose to handle list arguments with it—but it was a quick and dirty way to pass data from the Makefile without adding dependencies or doing custom parsing.

[loren-osborn]

Getting close to review ready...

• Need to increase test coverage
• Need to hook Makefiles to go implementation
• Need to delete stale partial bash implementation
• Need some final testing

[loren-osborn]

I'm sure there's something I forgot to fix, but I took care of all issues that I was aware of.

I computed and passed all the files and directories as arguments from make, but all the file parsing happens in Go now.