Team DX is serving the teams to provide documentation to our customers.
Shopware has its history of creating and maintaining self-build and self-hosted documentations, which went wild after the initial deployment, because there was no dedicated "owner" who directly maintained the docs and fixed bugs etc.
We want to make it easy for everyone to set up and maintain / preview / deploy the new documentation and have a dedicated "ownership" so people have less to worry about. Ultimately - we want the majority of teams to adopt that approach, not being force into. 🙂
This repository extends
shopware/developer-documentation-vitepress
and
embeds:
- shopware/docs
- shopware/frontends
- shopware/admin-extension-sdk
- shopware/meteor-icon-kit
- shopware/meteor-component-library
- shopware/store-api-reference
- shopware/admin-api-reference
Technically, the idea is to:
- provide Shopware Docs CLI (
./docs-cli
) for embedding, previewing and managing embedded resources - embed static files from a dedicated
docs
folder (source) in sub-repositories/projects to thedocs/mount-point
folder (destination) in this repository - have a single deployment workflow with the build being served from a single domain - https://beta-developer.shopware.com
See ./FEATURES.md for more info about built-in features.
Clone repository and change dir.
$ git clone ssh://git@github.com:shopware/developer-portal.git
$ cd developer-portal
Install NPM dependencies for all workspaces.
$ pnpm i
To embed some or all docs repositories, you first need to build CLI using cli:dev
(non-minimized build)
or cli:build
(minimized build) commands.
See ./DOCS.md for more info about Shopware Docs CLI.
$ pnpm cli:build
You can then run CLI.
# from a symlink
$ ./docs-cli
# from the source
$ ./cli/dist/docs-cli.js
Once you've built your CLI, you can embed selected docs repositories.
$ ./docs-cli embed
Run development preview.
$ pnpm dev
Development preview allows missing embeddings which will result in some URLs returning code 404.
Run production build which will create static dump in the ./.vitepress/dist/
directory. Production build requires all
docs repositories to be embedded.
$ pnpm build
Preview production build with httpd:2.4
in Docker container - http://localhost:8765.
$ pnpm preview
There are 4 test groups configured in package.json:scripts
:
test
- runs e2e vitest (& Playwright) tests in./__tests__/e2e/
using internal vitest server, allowing partial embeddingstest:build
- runs e2e vitest (& Playwright) tests in./__tests__/e2e/
using on-the-fly vitest build, requiring all docs repositories to be embeddedtest:cli
- runs CLI vitest tests in./__tests__/cli/
using pre-built./docs-cli
(./cli/dist/docs-cli.js
) andsandbox
directory as a working directorytest:cli:coverage
- runs coverage for CLI
E2E tests make sure all docs repositories are properly embedded and that all layout elements are available.
CLI tests make sure all features in CLI works as intended.