docs(vc-shell): clean up concepts/ for narrative-only role#58
Closed
maksimzinchuk wants to merge 3 commits into
Closed
docs(vc-shell): clean up concepts/ for narrative-only role#58maksimzinchuk wants to merge 3 commits into
maksimzinchuk wants to merge 3 commits into
Conversation
|
|
4 tasks
Set up the infrastructure to support framework-source documentation auto-synced from vc-shell. Content comes in a follow-up commit. - mkdocs.yml (developer-guide): switch Custom Apps Development to a single awesome-pages rest pattern (... | regex=^custom-apps-development/.+\.md$). Replaces the previous 75-line manual nav enumeration. awesome-pages walks .pages files at every level so adding new components/composables to vc-shell sources doesn't need an mkdocs.yml edit. - vc-shell-docs.css: Storybook iframe embeds, admonition styling, table-of-contents tweaks, frozen-version banner styling. - overrides/main.html: theme override hook for the version banner. - .github/workflows/protect-generated.yml: CI guard that blocks human edits to AUTO-GENERATED files inside the auto-managed subtree (components/, composables/, reference/api,modules/). Manual folders (introduction/, getting-started/, guides/, reference/migration,cli/) are skipped. Bypassed for vc-shell-docs-bot and PRs labeled 'auto-generated'. The docs-sync CLI lives in vc-shell; on release it runs against this repo, commits the result, and opens an auto-PR.
Initial sync of the normalized VC-Shell framework documentation under platform/developer-guide/docs/custom-apps-development/vc-shell/. Output of yarn docs:sync run against vc-shell main (after Phase 0 template normalization landed there as 8b8946ddb). Layout: - introduction/ manual narrative — overview, what-is, when-to-use - getting-started/ manual narrative — installation, create-your-app - concepts/ manual narrative stubs — paradigm explanations - components/ AUTO — 60 component docs across 7 groups - composables/ AUTO — 35 composable docs across 8 groups - guides/ manual narrative stubs — placeholder topics - reference/api/ AUTO — 9 API surface docs (directives, types, ...) - reference/modules/ AUTO — 2 module docs (assets, assets-manager) - reference/cli/ manual narrative — api-client-generator, create-vc-app - reference/migration/ manual narrative — version migration placeholder The 151 *.docs.md source files in vc-shell are the source of truth. docs-sync emits .pages files at every auto-managed folder; manual folders carry hand-written .pages and won't be touched by sync. Removes the legacy hand-curated VC-Shell pages from the previous nav structure (Essentials/Usage-Guides/Plugins/Shared/UI Components etc.) — replaced by the new layout above.
maksimzinchuk
force-pushed
the
docs/vc-shell-phase-0-migration
branch
from
9e30589 to
9409492
Compare
Manual cleanup that complements the auto-sync of vc-shell plugin docs (handled by the sync-docs CI workflow on the next vc-shell release). docs-sync only generates new files and updates AUTO .pages — it does not delete orphans, rename files, or edit manual .pages. - Delete 10 stale auto-synced files from concepts/ — their sources in vc-shell moved to category: plugins, so docs-sync emits them under plugins/ instead. Old concepts/<plugin>.md copies stay on disk otherwise (sync only reports orphans). - Rename concepts/permissions.md → concepts/permissions-model.md and update H1 to avoid collision with the new auto-synced plugins/permissions.md (a different file — the permissions plugin reference). - Rewrite concepts/.pages to list the 8 surviving narrative stubs only. Safe to land in any order relative to the auto-sync PR — deletes ten 404s either way, rename adds a new file, .pages edits internal nav within concepts/. The follow-up commit adds plugins/ to vc-shell/.pages once the auto-sync PR creates the folder.
maksimzinchuk
force-pushed
the
feat/plugins-cleanup
branch
from
4377c9b to
3b84355
Compare
maksimzinchuk
force-pushed
the
docs/vc-shell-phase-0-migration
branch
from
9409492 to
24ccff8
Compare
Collaborator
Author
|
Folded into PR #57 — all concepts/ cleanup (orphan deletions, permissions-model rename, narrative-only .pages) now lives in the migration commit directly. The auto-PR from sync-docs.yml on the next vc-shell release populates plugins/ from CI, no manual orphan-cleanup needed. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Manual cleanup that complements the auto-sync of vc-shell plugin docs (handled by the
sync-docsCI workflow on the next vc-shell release). The auto-sync only generates new files and updates AUTO.pages— it does NOT delete orphans, rename files, or edit manual.pages. This PR covers those manual steps.What changes
concepts/:ai-agent,extension-points,global-error-handler,i18n,modularity,notifications,permissions-plugin,services,signalr,validation. Their sources in vc-shell moved tocategory: plugins, so docs-sync emits them underplugins/instead. Oldconcepts/<plugin>.mdcopies stay on disk otherwise (sync only reports orphans).concepts/permissions.md→concepts/permissions-model.md(narrative stub) to avoid future collision with the new auto-syncedplugins/permissions.md(a different file — the permissions plugin reference). H1 updated to match.concepts/.pagesto list the 8 surviving narrative stubs only (Blade Navigation, Modules, Extensions, Layout, Permissions Model, Localization, State Persistence, API Clients).Sequencing
Safe to land in any order relative to the auto-sync PR that
sync-docs.ymlwill open after the next vc-shell release (VirtoCommerce/vc-shell#223 lands first to enable that workflow).The companion follow-up —
add plugins to nav order— must land AFTER the auto-sync PR creates theplugins/folder.Related
pluginscategory): feat(docs-sync): introduce Plugins category vc-shell#223Test plan
mkdocs build -f platform/developer-guide/mkdocs.yml— no warnings about removed concept filesmkdocs serve— sidebar shows clean concepts/ section with 8 narrative stubs