Docs from the record
Generate component and token docs from a design system release, preview them and publish them to your docs repo.
In the pilot
The design system module is in the pilot. It is on for pilot orgs first. An org admin can tell you whether yours has it.
Every design system release comes with its docs. EasyCode writes them from the record: one page per component, one per token group and an index. You can read them in EasyCode, and a maintainer can publish them to your docs repo as a pull request. Nothing is published unless someone presses Publish.
Before you start:
- Your org needs the
designmodule. When staff turn off thedesignkill switch, docs are unavailable. See kill switches and modules. - Anyone with a role on the system can read its docs.
- Only the system's maintainers and org admins can publish. Members see the docs without the Publish docs button.
- Publishing needs a docs repo: a Docs site source on the system that names the repo and the folder the pages go in. Without one, the pages live only in EasyCode.
Desktop app only
Publishing runs on your machine, with your own git and gh logins. On the cloud web the button is disabled and reads "Publish from the desktop app".
What the docs hold
The docs are made for releases only, never for unreleased changes. Each page comes from the release's record:
- A component page: its summary and status, how to install it, its props with types, defaults and whether they are required, its parts, the tokens it uses, and links to its stories. A component the release added, changed, deprecated or removed says so.
- A token group page: each token with its base value and its value in each theme.
- An index that links them all.
A field the record lacks leaves its section out rather than showing an empty heading. Story links appear only for hosts your admin approved. The same release always gives the same pages, byte for byte.
Read a release's docs
Open the design system and go to Releases.
Open a release and scroll to its Docs block.
Pick a page from the list on the left. Each shows its size. A release with more than 200 components shows the first 200 and Show all.
A component's own page also has a Docs section with that component's page from the latest release. If you are looking at unreleased changes, it says "Docs are made for releases" and links to the latest release's docs.
Other states you may see:
- "No release yet. Docs appear with the first release."
- "Withdrawn: its tag was deleted or moved". The pages still show, and nothing can be published from that release.
Publish to your docs repo
On the release's Docs block, press Publish docs.
Read the preview. It compares the pages with your docs repo's default branch and lists, with counts and paths:
- add: new pages;
- change: pages that differ;
- delete: generated pages this release no longer has;
- kept: generated pages someone edited in the docs repo since the last publish, which EasyCode leaves alone;
- replaced: hand-written pages your docs site source says the generated ones replace.
The preview also shows the branch name, such as easycode/docs-northwind-ui-1.2.0, and the pull request's title. Nothing is written yet.
To overwrite the edited pages too, tick Overwrite pages edited in the docs repo. It is off by default.
Press Publish.
EasyCode makes the branch from your docs repo's default branch, writes exactly the planned files, makes one commit and pushes it with your own git login. It then opens the pull request with your gh. The dialog links Docs pull request with its number. Review and merge it as any other pull request; your docs site's own pipeline deploys it. EasyCode hosts nothing.
Hand-written files in the docs folder that EasyCode never generated, and that are not on the replaced list, are never touched.
After you publish
The release's Docs block shows the docs pull request with its state. If you can't read the docs repo on GitHub, it says "A docs pull request is open" without a link.
If you publish the same release again once its pull request is merged, the preview's groups are empty and Publish answers "Nothing to publish": the docs repo already matches the release. No pull request is opened.
When publishing fails
The dialog says what went wrong:
- "The docs repo moved. Preview again." The default branch changed since your preview.
- "Your GitHub login can't push to this repo." Ask for write access to the docs repo.
- "Sign in to the GitHub CLI on this machine." Run
gh auth login, then try again. - "A git hook refused the docs publish." Check the docs repo's hooks.
- "Open this organisation on your machine to publish docs." Open the org in the desktop app first.
Related
Something wrong or missing? Suggest a change
Found versions and update tasks
How EasyCode finds the design system version each product is on and keeps one update task per product and system.
X-ray and conformance
Label every element of a page in the desktop browser by design system, file a one-off as a request, and add a conformance block to a pull request.