Skip to content

docs: Add reference documentation for plugin #109

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.

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

Merged
merged 1 commit into from
Apr 24, 2025

Conversation

euanh
Copy link
Collaborator

@euanh euanh commented Apr 24, 2025

Motivation

Reference documentation, such as manual pages, complements getting started guides and tutorials by explaining a tool's interface and options in one place.

The build-container-image command plugin is the main user-facing tool in the project, so users will benefit from having reference documentation for it, available from the main documentation site.

At present, containertool will mostly be used through the plugin, which is a thin wrapper which calls containertool as a helper. Documenting containertool as a separate tool might be confusing. It has command line help for those who need to use it directly, and as the plugin is largely a wrapper its reference documentation also explains most of containertool's options.

Modifications

  • Rewrite the containertool manual page for the build-container-image plugin.
  • Add a Reference section to the curation, linking to the plugin manual page.

Result

Users have access to reference documentation which explains the interface and options of the build-container-image command plugin.

Test Plan

All existing tests continue to pass.

@euanh euanh marked this pull request as ready for review April 24, 2025 12:42
@euanh euanh requested a review from heckj April 24, 2025 12:42
@euanh euanh added area/documentation Improvements or additions to documentation semver/none No version bump required. labels Apr 24, 2025
@euanh euanh changed the title docs: Add reference documentation (manual page) for plugin docs: Add reference documentation for plugin Apr 24, 2025
@euanh euanh force-pushed the docs/plugin-manual-page branch from 05281d5 to db7e859 Compare April 24, 2025 13:25
Copy link
Collaborator

@heckj heckj left a comment

Choose a reason for hiding this comment

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

I'm guessing you created this by hand vs. using the generator command plug in swift argument parser? (I suspect by hand, as I don't think the plugin uses term lists unless you used the most recent build where I just added it)

The term lists are a great touch here!

@euanh euanh force-pushed the docs/plugin-manual-page branch from db7e859 to c8925f4 Compare April 24, 2025 17:44
@euanh
Copy link
Collaborator Author

euanh commented Apr 24, 2025

Yes, I did this by hand. I started with the help output for containertool and adapted it, because the plugin's own help text is quite limited.

I don't think it's currently possible to generate help for a plugin itself because plugins can't use swift-argument-parser.

@euanh euanh merged commit 53f2960 into apple:main Apr 24, 2025
23 checks passed
@euanh euanh deleted the docs/plugin-manual-page branch April 24, 2025 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/documentation Improvements or additions to documentation semver/none No version bump required.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants