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.

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

Document all targets in project.Makefile #1278

Open
eecavanna opened this issue Nov 3, 2023 · 1 comment · May be fixed by #2007
Open

Document all targets in project.Makefile #1278

eecavanna opened this issue Nov 3, 2023 · 1 comment · May be fixed by #2007
Assignees
@turbomam
Labels
documentation Improvements or additions to documentation

Comments

@eecavanna
Copy link
Contributor

Running $ make {some_target} seems to me to be something contributors to this repo do often.

I don't know what the various make targets do. I recommend adding a comment above each one, that says what it does.
@eecavanna eecavanna added the documentation Improvements or additions to documentation label Nov 3, 2023
@turbomam turbomam mentioned this issue Nov 3, 2023
Open
@eecavanna
Copy link
Contributor Author

I found one approach for documenting a Makefile's targets:
https://stackoverflow.com/a/47107132

The approach seems a little fragile to me (e.g. leading to people wondering "why's it working on line X, but not on line Y, as they look similar to me...?"), but it would give us at least the following two benefits:

  • The ability to display the help for each command, all at once
  • A standard way to document the targets

@eecavanna eecavanna mentioned this issue Feb 24, 2024
Closed
@eecavanna eecavanna linked a pull request May 26, 2024 that will close this issue
Implement PoC of Makefile target documentation pattern #2007
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@turbomam turbomam

Labels
documentation Improvements or additions to documentation
Projects
NMDC Hackathons Board
Status: No status
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Implement PoC of Makefile target documentation pattern microbiomedata/nmdc-schema
2 participants
@turbomam @eecavanna