Skip to content

📖 [Docs]: Document grouped public command help URLs #453

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

Draft
Marius Storhaug (MariusStorhaug) wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −0
Draft

📖 [Docs]: Document grouped public command help URLs #453

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/content/guides/structuring-your-module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,14 @@ Key expectations:
- A group's overview page (`<Category>/<Category>.md` named after the folder, or `<Category>/index.md`) becomes that group's section landing page in the docs navigation.
- The build step compiles `src/` into a root module file and removes the original project layout from the artifact.
- Documentation generation mirrors the `src/functions/public` hierarchy so help content always aligns with source.
- Put the canonical public help URL first in each public command's comment-based help. For a command at `src/functions/public/<Group>/<Name>.ps1`, use `https://psmodule.io/<ModuleName>/Functions/<Group>/<Name>/`. `Test-PSModule` enforces this as `PublicHelpLink`; additional `.LINK` entries may follow.
- Point each private helper's `.LINK` entry to the public command it supports, using that command's canonical grouped URL.

### Grouping and published help URLs

`Document-PSModule` generates command help and then moves each page to mirror the relative path under `src/functions/public/`. Moving an existing command into a group therefore changes its published URL from `https://psmodule.io/<ModuleName>/Functions/<Name>/` to `https://psmodule.io/<ModuleName>/Functions/<Group>/<Name>/`.

When regrouping a command, update its first public `.LINK`, every private-helper `.LINK` that points to it, and any other references to the old URL in the same change. `Document-PSModule` does not create redirects for the old path; arrange a redirect separately in the publishing layer when existing links must continue to work.

## Module source code structure

Expand Down