Skip to content

Conversation

@patrickbrophy
Copy link
Contributor

This PR addresses issue #2472. This PR allows for documentation to be automatically generated using the go generate command. A minor implementation note, I had to put the generation code in the cmd package because of how Go handles accessing exported variable inside the main package.

@patrickbrophy patrickbrophy added documentation Improvements or additions to documentation client Issue affecting the OSDF client labels Aug 8, 2025
@h2zh
Copy link
Contributor

h2zh commented Aug 8, 2025

The approach to auto-generating the CLI docs is really clever. Having said that, I think what's implemented in this PR doesn't totally reflect the requirements in the ticket created by @aowen-uwmad. My understanding was that the goal is to have the docs live on the documentation website directly. The current implementation seems to require users to run a manual command to generate and view them. Maybe it is just an intermediate PR?

@CannonLock
Copy link
Contributor

@patrickbrophy These errors aren't tied to anything I can help with. My guess from looking through things is that when Haoming set this up he held an assumption of run order so things didn't break. I see some placeholder magic in the generate folder.

Maybe add this to the generate directory with the other scripts?

@patrickbrophy patrickbrophy linked an issue Sep 8, 2025 that may be closed by this pull request
7 tasks
@patrickbrophy patrickbrophy force-pushed the doc-gen branch 4 times, most recently from 546c437 to 2bc8aa3 Compare September 8, 2025 20:21
@aowen-uwmad
Copy link
Contributor

@patrickbrophy , I know there are some "hidden" commands that dev team doesn't necessarily want users to know about..
Does your auto-generation take those into account (and not generate those pages)?

@patrickbrophy
Copy link
Contributor Author

Yes the generator takes that into account. A command is "hidden" when the Command.Hidden field is set to true. Below is a screenshot showing that the object delete command is hidden:
image

@patrickbrophy
Copy link
Contributor Author

I have updated the layout to be less nested and a lowercase like how our commands are written in the terminal.

image

@patrickbrophy patrickbrophy marked this pull request as ready for review September 18, 2025 21:31
@aowen-uwmad
Copy link
Contributor

The screenshot of the updated navigation bar looks good to me.

Copy link
Contributor

@aowen-uwmad aowen-uwmad left a comment

Choose a reason for hiding this comment

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

I did a local preview and explored the commands reference pages; I think it looks good.
I can't speak to the Go or CI/CD pieces, though, so someone else should review that to approve this.

@aowen-uwmad
Copy link
Contributor

This PR is blocked by #1765. Will need to be refactored to address the changes in there.

@patrickbrophy patrickbrophy marked this pull request as draft November 5, 2025 16:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

client Issue affecting the OSDF client documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create "Commands Reference" page for the docs website

4 participants