Skip to content

docs: Split ContainerBuildPlugin documentation into multiple pages#99

Merged
euanh merged 17 commits intoapple:mainfrom
euanh:docs/restructure
Apr 17, 2025
Merged

docs: Split ContainerBuildPlugin documentation into multiple pages#99
euanh merged 17 commits intoapple:mainfrom
euanh:docs/restructure

Conversation

@euanh
Copy link
Copy Markdown
Collaborator

@euanh euanh commented Apr 16, 2025

Motivation

Most of the documentation explaining how a user should run the plugin is in a single DoCC file under the ContainerImageBuilderPlugin target (this otherwise empty target is needed because DoCC does not generate documentation for plugins).

This documentation would be easier to read, and easier to expand with more information, if it was split into several sections. This would provide an outline view in the left-hand pane (the "curation") which would allow users to jump directly to sections of interest, and make internal links between documentation sections easier.

Modifications

  • Rename ContainerImageBuilderPlugin to swift-container-plugin. swift-container-plugin will hold all the high level documentation, examples and tutorials for the project. A future PR will add a manual page which specifically covers only the plugin.

Result

The existing documentation is better structured. A number of small edits have been made for clarity.

Test Plan

  • No functional change.
  • DoCC checks are already run by the soundness GitHub CI job and continue to pass; all notes and usage warnings fixed.

@euanh euanh marked this pull request as ready for review April 16, 2025 15:42
Copy link
Copy Markdown
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 not sure if the > Note: block pieces will work as I'm hoping, but I think it would sit better in that field if we can wrangle it. The rest of the updates are minor structure nits and wording choices that just tighten things up a bit.

Co-authored-by: Joseph Heck <j_heck@apple.com>
@euanh euanh added area/documentation Improvements or additions to documentation semver/none No version bump required. labels Apr 17, 2025
@euanh euanh merged commit c148c56 into apple:main Apr 17, 2025
23 checks passed
@euanh euanh deleted the docs/restructure branch April 17, 2025 16:39
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