Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): read a section of a docs-tree namespace from the guide that has it (#7212)

Joey4ec0d0e9e68a
diff --git a/.changeset/layout-docs-namespace.md b/.changeset/layout-docs-namespace.md
index 80fc18cc88..854680566d 100644
--- a/.changeset/layout-docs-namespace.md
+++ b/.changeset/layout-docs-namespace.md
@@ -2,7 +2,7 @@
'@astryxdesign/cli': patch
---
-[docs] `astryx docs layout` still works and now lists the focused guides. Section reads move under them, for example `astryx docs layout/side-panels` or `astryx docs layout/scaffold shell`; the old `astryx docs layout <section>` form no longer resolves.
+[docs] `astryx docs layout` still works and now lists the focused guides. Each section is also readable under its guide, for example `astryx docs layout/side-panels` or `astryx docs layout/scaffold shell`, and `astryx docs layout <section>` keeps working.
(#7125)
@josephfarina
diff --git a/.changeset/namespace-section-reads.md b/.changeset/namespace-section-reads.md
new file mode 100644
index 0000000000..d8a54055a9
--- /dev/null
+++ b/.changeset/namespace-section-reads.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] A section read on a docs-tree namespace answers from the guide that has the section again, so `astryx docs layout side-panels` and the other layout section reads released in 0.6.6 work after the layout split. `docs(route, section)` returns the same `docs.detail.section` the guide's own section read returns, found by key, then by title, in `--dense` and `--zh` too. When no guide or more than one has the section, the read fails with `ERR_UNKNOWN_SECTION` and names the guides to read it from.
+
+@josephfarina
diff --git a/packages/cli/api/docs/detail/section/section.mjs b/packages/cli/api/docs/detail/section/section.mjs
index c4968525fe..acd7fad498 100644
--- a/packages/cli/api/docs/detail/section/section.mjs
+++ b/packages/cli/api/docs/detail/section/section.mjs
@@ -11,6 +11,9 @@
* token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
* Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
* more than one section (the candidates come back as suggestions).
+ * A namespace's section read (spec:AST-046 FR6) finds the one guide below the
+ * namespace that has the section and answers exactly as that guide's section
+ * read does.
* @position Leaf nested under api/docs/detail. Shares topic resolution with the
* detail leaf via _adapter.mjs and reads through the compiler's lenses.
*/
@@ -20,6 +23,8 @@ import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
import {
findDocSection,
sectionKey,
+ sectionTitleKey,
+ sourceTitle,
} from '../../../../foundation/discovery/docs-section-key.mjs';
import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
import {
@@ -43,19 +48,9 @@ import {
* @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
*/
export async function section(topic, sectionName, options = {}) {
- // An empty section name must error, not resolve to the first section. The
- // docs() dispatcher routes a falsy section to the topic, but the leaf must be
- // safe on its own; a non-string would otherwise throw a raw TypeError.
- if (typeof sectionName !== 'string' || !sectionName.trim()) {
- throw new AstryxError(
- 'A section name is required',
- undefined,
- ERROR_CODES.ERR_UNKNOWN_SECTION,
- );
- }
-
- const {catalog, node, lang, entry} = await resolveTopicDocs(topic, options);
- const sections = readerSections(node);
+ requireSectionName(sectionName);
+ const resolved = await resolveTopicDocs(topic, options);
+ const sections = readerSections(resolved.node);
const {section: match} = findDocSection(sections, sectionName);
if (!match) {
throw new AstryxError(
@@ -68,6 +63,33 @@ export async function section(topic, sectionName, options = {}) {
);
}
+ return sectionResponse(resolved, sections, match);
+}
+
+/**
+ * An empty section name must error, not resolve to the first section. The
+ * docs() dispatcher routes a falsy section to the topic, but a leaf must be
+ * safe on its own; a non-string would otherwise throw a raw TypeError.
+ * @param {unknown} sectionName
+ */
+function requireSectionName(sectionName) {
+ if (typeof sectionName !== 'string' || !sectionName.trim()) {
+ throw new AstryxError(
+ 'A section name is required',
+ undefined,
+ ERROR_CODES.ERR_UNKNOWN_SECTION,
+ );
+ }
+}
+
+/**
+ * The docs.detail.section response for one section of a resolved topic.
+ * @param {Awaited<ReturnType<typeof resolveTopicDocs>>} resolved
+ * @param {any[]} sections the topic's reader sections
+ * @param {any} match one of them
+ * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
+ */
+async function sectionResponse({catalog, node, lang, entry}, sections, match) {
// A section read on its own inlines its token refs, as the whole topic does;
// otherwise a section that is only a token-ref prints blank. Only this
// section is linked, so a broken reference elsewhere cannot fail the read.
@@ -93,3 +115,132 @@ export async function section(topic, sectionName, options = {}) {
data: {...sectionView(node, linked), links},
};
}
+
+/**
+ * @typedef {object} GuideMatch
+ * @property {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} guide
+ * @property {Awaited<ReturnType<typeof resolveTopicDocs>>} resolved
+ * @property {any[]} sections the guide's reader sections
+ * @property {any} match the section it has
+ */
+
+/**
+ * One section of a namespace (spec:AST-046 FR6): the section read of the one
+ * guide below the namespace, at any depth, that has it. Each guide answers
+ * with the section its own section read returns for the query; when that
+ * section's key (its `id`, else the key its title derives) is the query in
+ * some guides, those guides answer first. No guide, or several, fail with ERR_UNKNOWN_SECTION, naming
+ * the guides to read instead.
+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').DocsTree} tree
+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} namespace
+ * @param {string} sectionName
+ * @param {object} [options] as {@link section}
+ * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
+ */
+export async function namespaceSection(
+ tree,
+ namespace,
+ sectionName,
+ options = {},
+) {
+ requireSectionName(sectionName);
+ const guides = guidesBelow(tree, namespace);
+ /** @type {Omit<GuideMatch, 'match'>[]} */
+ const reads = [];
+ for (const guide of guides) {
+ const resolved = await resolveTopicDocs(guide.route, options);
+ reads.push({guide, resolved, sections: readerSections(resolved.node)});
+ }
+
+ const wanted = sectionName.trim();
+ const derived = sectionTitleKey(wanted);
+ /** @type {GuideMatch[]} */
+ const byKey = [];
+ /** @type {GuideMatch[]} */
+ const found = [];
+ for (const read of reads) {
+ // The section the guide's own section read returns for this query, so the
+ // namespace read answers exactly what `astryx docs <guide> <section>` does.
+ const {section: match} = findDocSection(read.sections, wanted);
+ if (!match) continue;
+ found.push({...read, match});
+ if (
+ sectionKey(match) === wanted ||
+ (derived !== '' && sectionTitleKey(sourceTitle(match)) === derived)
+ ) {
+ byKey.push({...read, match});
+ }
+ }
+ const matches = byKey.length > 0 ? byKey : found;
+ const chosen = oneGuide(matches);
+ if (chosen)
+ return sectionResponse(chosen.resolved, chosen.sections, chosen.match);
+
+ if (guides.length === 0) {
+ // A namespace with no guide below it (a reference level such as cli/api)
+ // has no sections to read: name its children, as before.
+ throw new AstryxError(
+ `"${namespace.route}" has no sections. Open one of its children instead.`,
+ namespace.slots.flatMap(slot =>
+ slot.children.map(route => ({
+ name: route,
+ reason: tree.get(route)?.summary ?? '',
+ })),
+ ),
+ ERROR_CODES.ERR_UNKNOWN_SECTION,
+ );
+ }
+ if (matches.length === 0) {
+ throw new AstryxError(
+ `Section "${sectionName}" is not in any guide under "${namespace.route}". Open one of its guides instead.`,
+ guides.map(guide => ({name: guide.route, reason: guide.summary})),
+ ERROR_CODES.ERR_UNKNOWN_SECTION,
+ );
+ }
+ throw new AstryxError(
+ `Section "${sectionName}" matches sections in more than one guide under "${namespace.route}". Read it from one of them.`,
+ matches.map(({guide, match}) => ({
+ name: guide.route,
+ reason: `has "${match.title}"`,
+ })),
+ ERROR_CODES.ERR_UNKNOWN_SECTION,
+ );
+}
+
+/**
+ * The guide a namespace section read answers from, or null to ask. When the
+ * query matches sections in several guides, the read asks the reader which
+ * guide they mean (spec:AST-046 FR6), where a flat topic's section read
+ * returned its first title match. To return the first match in tree order
+ * instead, return `matches[0]` here.
+ * @param {GuideMatch[]} matches in tree order
+ * @returns {GuideMatch | null}
+ */
+export function oneGuide(matches) {
+ return matches.length === 1 ? matches[0] : null;
+}
+
+/**
+ * Every guide below a namespace, at any depth, in tree order.
+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').DocsTree} tree
+ * @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} namespace
+ * @returns {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode[]}
+ */
+function guidesBelow(tree, namespace) {
+ /** @type {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode[]} */
+ const guides = [];
+ /** @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} parent */
+ const walk = parent => {
+ for (const slot of parent.slots) {
+ for (const route of slot.children) {
+ const child = tree.get(route);
+ if (!child || child.parent !== parent.route) continue;
+ if (child.kind === 'namespace') walk(child);
+ else if (child.kind === 'generic' && child.ref?.topicFile)
+ guides.push(child);
+ }
+ }
+ };
+ walk(namespace);
+ return guides;
+}
diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjs
index 798e600baf..fb5d1dab02 100644
--- a/packages/cli/api/docs/docs.doc.mjs
+++ b/packages/cli/api/docs/docs.doc.mjs
@@ -121,7 +121,7 @@ export const doc = {
{
type: 'docs.detail.section',
description:
- 'One ReferenceSection of the topic, found by key or title, with token-ref and reference blocks inlined.',
+ 'One ReferenceSection of the topic, found by key or title, with token-ref and reference blocks inlined. Asked of a docs-tree namespace, it is the section read of the one guide below the namespace that has the section.',
},
{
type: 'docs.node',
@@ -144,7 +144,7 @@ export const doc = {
},
{
code: 'ERR_UNKNOWN_SECTION',
- when: 'a section is requested but is empty, matches no section, matches more than one, or is asked of a docs-tree namespace or typed doc, which have no sections',
+ when: 'a section is requested but is empty, matches no section, or matches more than one; asked of a docs-tree namespace, when no guide below it or more than one has the section (suggestions name those guides); or asked of a typed doc, which has no sections',
},
],
examples: [
diff --git a/packages/cli/api/docs/docs.mjs b/packages/cli/api/docs/docs.mjs
index 4b8fe12dcd..d6d090a44d 100644
--- a/packages/cli/api/docs/docs.mjs
+++ b/packages/cli/api/docs/docs.mjs
@@ -26,7 +26,10 @@
import {list} from './list/list.mjs';
import {index} from './index/index.mjs';
import {detail} from './detail/detail.mjs';
-import {section as sectionLeaf} from './detail/section/section.mjs';
+import {
+ namespaceSection,
+ section as sectionLeaf,
+} from './detail/section/section.mjs';
import {node as nodeLeaf, nodeView} from './node/node.mjs';
import {resolveDocsArgument} from './_adapter.mjs';
import {AstryxError} from '../error.mjs';
@@ -98,23 +101,15 @@ export async function docs(topic, section, options = {}) {
if (!topic) return list(options);
const found = await resolveDocsArgument(topic, options);
if (found.kind === 'node') {
- // A namespace or a typed doc has no sections: it is one read. `--index`
- // asks for what the node read already is.
if (section) {
+ // A namespace answers a section read from the one guide below it that
+ // has the section (spec:AST-046 FR6). A typed doc is one read.
+ if (found.node.kind === 'namespace') {
+ return namespaceSection(found.tree, found.node, section, options);
+ }
throw new AstryxError(
- `"${found.node.route}" has no sections. ${
- found.node.kind === 'namespace'
- ? 'Open one of its children instead.'
- : `Read it whole: astryx docs ${found.node.route}.`
- }`,
- found.node.kind === 'namespace'
- ? found.node.slots.flatMap(slot =>
- slot.children.map(route => ({
- name: route,
- reason: found.tree.get(route)?.summary ?? '',
- })),
- )
- : [{name: found.node.route, reason: found.node.summary}],
+ `"${found.node.route}" has no sections. Read it whole: astryx docs ${found.node.route}.`,
+ [{name: found.node.route, reason: found.node.summary}],
ERROR_CODES.ERR_UNKNOWN_SECTION,
);
}
diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjs
index a3f622a2cc..0f897d9771 100644
--- a/packages/cli/api/docs/docs.test.mjs
+++ b/packages/cli/api/docs/docs.test.mjs
@@ -240,16 +240,15 @@ describe('docs() dispatcher routing', () => {
);
}, SLOW);
- it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {
- const err = await docs('cli', 'commands').catch(e => e);
+ it('a section no guide of a namespace has -> ERR_UNKNOWN_SECTION, naming its guides', async () => {
+ const err = await docs('cli', 'zzzz-nope').catch(e => e);
expect(err).toBeInstanceOf(AstryxError);
expect(err.code).toBe('ERR_UNKNOWN_SECTION');
- // It names the namespace's children, in the order its slots list them.
- const cli = (await docs('cli')).data;
- expect(err.suggestions.map(s => s.name)).toEqual(
- cli.slots.flatMap(slot => slot.children.map(child => child.route)),
- );
- expect(err.suggestions.map(s => s.name)).toContain('cli/commands');
+ // It names every guide below the namespace, at any depth.
+ const names = err.suggestions.map(s => s.name);
+ expect(names).toContain('cli/component-lookups');
+ expect(names).toContain('cli/integrations/quick-start');
+ expect(names.every(name => name.startsWith('cli/'))).toBe(true);
}, SLOW);
it('an unknown route suggests the children of the deepest namespace it reaches', async () => {
diff --git a/packages/cli/api/docs/namespace-section.test.mjs b/packages/cli/api/docs/namespace-section.test.mjs
new file mode 100644
index 0000000000..3826e95292
--- /dev/null
+++ b/packages/cli/api/docs/namespace-section.test.mjs
@@ -0,0 +1,260 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A section read on a namespace (spec:AST-046 FR6): `astryx docs
+ * <namespace> <section>` answers from the one guide below the namespace that
+ * has the section, exactly as that guide's own section read does, so a section
+ * read that worked before a topic became a namespace still works.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {docs} from './docs.mjs';
+import {oneGuide} from './detail/section/section.mjs';
+
+const SLOW = 60_000;
+
+/** @type {string} */
+let tmpDir;
+
+/** @param {Record<string, object>} files the integration's doc files */
+function scaffold(files) {
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: 'consumer'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.mjs'),
+ "export default {integrations: ['@acme/kit']};\n",
+ );
+ const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'kit');
+ fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});
+ fs.writeFileSync(
+ path.join(pkgDir, 'package.json'),
+ JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'astryx.integration.mjs'),
+ "export default {docs: './docs'};\n",
+ );
+ for (const [file, doc] of Object.entries(files)) {
+ fs.writeFileSync(
+ path.join(pkgDir, 'docs', file),
+ `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
+ );
+ }
+}
+
+/**
+ * @param {string} name
+ * @param {number} order
+ * @param {Array<{title: string, id?: string}>} sections
+ */
+function guide(name, order, sections) {
+ return {
+ type: 'generic',
+ name,
+ title: `Acme ${name}`,
+ description: `The ${name} guide.`,
+ placement: {parent: 'namespace:acme', slot: 'guides', order},
+ sections: sections.map(section => ({
+ ...section,
+ content: [{type: 'prose', text: `${section.title} text.`}],
+ })),
+ };
+}
+
+/** A namespace of two guides that both have a section titled "...setup". */
+function kit() {
+ return {
+ 'acme.doc.mjs': {
+ type: 'namespace',
+ name: 'acme',
+ title: 'Acme',
+ summary: 'Everything about the Acme kit.',
+ slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},
+ },
+ 'install.doc.mjs': guide('install', 1, [
+ {title: 'Package setup', id: 'package-setup'},
+ {title: 'Verify'},
+ ]),
+ 'theme.doc.mjs': guide('theme', 2, [
+ {title: 'Theme setup'},
+ {title: 'Dark mode'},
+ ]),
+ };
+}
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(
+ path.join(process.cwd(), '.astryx-namespace-section-test-'),
+ );
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('a section read on a namespace', () => {
+ it(
+ 'returns the one guide section, by key and by title, as the guide read does',
+ async () => {
+ for (const query of ['side-panels', 'Side panels', 'side panels']) {
+ const read = await docs('layout', query);
+ expect(read).toEqual(await docs('layout/side-panels', 'side-panels'));
+ expect(read).toMatchObject({
+ type: 'docs.detail.section',
+ package: '@astryxdesign/cli',
+ data: {id: 'side-panels', title: 'Side panels'},
+ });
+ }
+ // A section in a guide of its own, and a section past a guide's first.
+ expect((await docs('layout', 'shell')).data.id).toBe('shell');
+ expect((await docs('layout', 'responsive-contract')).data.id).toBe(
+ 'responsive-contract',
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'reads dense and Chinese the way the guide read does',
+ async () => {
+ for (const options of [{dense: true}, {zh: true}, {lang: 'dense'}]) {
+ expect(await docs('layout', 'side-panels', options)).toEqual(
+ await docs('layout/side-panels', 'side-panels', options),
+ );
+ }
+ },
+ SLOW,
+ );
+
+ it(
+ "prefers the guide whose section key is the query over another guide's title match",
+ async () => {
+ scaffold(kit());
+ const read = await docs('acme', 'package-setup', {cwd: tmpDir});
+ expect(read.data).toMatchObject({
+ id: 'package-setup',
+ title: 'Package setup',
+ });
+ expect(read.data.links.up).toBe('astryx docs acme/install --index');
+ expect((await docs('acme', 'dark mode', {cwd: tmpDir})).data.title).toBe(
+ 'Dark mode',
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'fails on a miss, naming every guide below the namespace',
+ async () => {
+ const err = await docs('layout', 'zzzz-nope').catch(e => e);
+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+ const names = err.suggestions.map(s => s.name);
+ expect(names).toContain('layout/scaffold');
+ expect(names).toContain('layout/side-panels');
+ expect(names.every(name => name.startsWith('layout/'))).toBe(true);
+ // At any depth: guides under nested namespaces are named, namespaces are not.
+ const cli = await docs('cli', 'zzzz-nope').catch(e => e);
+ expect(cli.code).toBe('ERR_UNKNOWN_SECTION');
+ expect(cli.suggestions.map(s => s.name)).toContain(
+ 'cli/integrations/quick-start',
+ );
+ expect(cli.suggestions.map(s => s.name)).not.toContain(
+ 'cli/integrations',
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'still fails a section on a typed doc, naming the doc',
+ async () => {
+ const err = await docs('cli/commands/docs', 'anything').catch(e => e);
+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+ expect(err.suggestions.map(s => s.name)).toEqual(['cli/commands/docs']);
+ },
+ SLOW,
+ );
+});
+
+describe('a namespace read answers what the guide read answers', () => {
+ /** A guide with a title match before a key match, and a second guide. */
+ function competing() {
+ return {
+ ...kit(),
+ 'install.doc.mjs': guide('install', 1, [
+ {title: 'Shell contract'},
+ {title: 'Shell'},
+ ]),
+ 'theme.doc.mjs': guide('theme', 2, [{title: 'Setup', id: 'setup'}]),
+ 'extra.doc.mjs': guide('extra', 3, [{title: 'Theme setup'}]),
+ };
+ }
+
+ it(
+ 'returns the section the guide read returns, even when a later section has the key',
+ async () => {
+ scaffold(competing());
+ const own = await docs('acme/install', 'shell', {cwd: tmpDir});
+ const read = await docs('acme', 'shell', {cwd: tmpDir});
+ expect(read).toEqual(own);
+ expect(read.data.title).toBe('Shell contract');
+ },
+ SLOW,
+ );
+
+ it(
+ "prefers the guide whose own match is the query's key over another guide's title match",
+ async () => {
+ scaffold(competing());
+ const read = await docs('acme', 'setup', {cwd: tmpDir});
+ expect(read).toEqual(await docs('acme/theme', 'setup', {cwd: tmpDir}));
+ expect(read.data).toMatchObject({id: 'setup', title: 'Setup'});
+ },
+ SLOW,
+ );
+
+ it(
+ 'names the children of a namespace with no guide below it',
+ async () => {
+ const err = await docs('cli/api', 'anything').catch(e => e);
+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+ const api = (await docs('cli/api')).data;
+ expect(err.suggestions.map(s => s.name)).toEqual(
+ api.slots.flatMap(slot => slot.children.map(child => child.route)),
+ );
+ expect(err.suggestions.length).toBeGreaterThan(0);
+ expect(err.message).toContain('Open one of its children');
+ },
+ SLOW,
+ );
+});
+
+describe('a section query that matches sections in several guides', () => {
+ // It used to guess; now it asks. A flat topic's section read returns its
+ // first title match; across guides, the read names each guide instead.
+ it(
+ 'asks which guide, naming each guide that matches',
+ async () => {
+ scaffold(kit());
+ const err = await docs('acme', 'setup', {cwd: tmpDir}).catch(e => e);
+ expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+ expect(err.suggestions).toEqual([
+ {name: 'acme/install', reason: 'has "Package setup"'},
+ {name: 'acme/theme', reason: 'has "Theme setup"'},
+ ]);
+ },
+ SLOW,
+ );
+
+ it('decides in one place: oneGuide answers only a single match', () => {
+ const a = /** @type {any} */ ({guide: {route: 'acme/install'}});
+ const b = /** @type {any} */ ({guide: {route: 'acme/theme'}});
+ expect(oneGuide([a])).toBe(a);
+ expect(oneGuide([a, b])).toBeNull();
+ expect(oneGuide([])).toBeNull();
+ });
+});
diff --git a/packages/cli/clients/cli/commands/docs.doc.mjs b/packages/cli/clients/cli/commands/docs.doc.mjs
index 7ccced889f..cd16e1bf05 100644
--- a/packages/cli/clients/cli/commands/docs.doc.mjs
+++ b/packages/cli/clients/cli/commands/docs.doc.mjs
@@ -22,7 +22,8 @@ export const doc = {
'does, and `--index` its section index. A route ' +
'opens a node of the docs tree: `cli` lists its guides and reference, ' +
'`cli/api/functions` lists every API function, and `cli/api/functions/search` prints ' +
- 'one. `--depth` reads as far down the tree as you ask, from the doc alone (0) to ' +
+ 'one. A namespace plus a section prints that section from the one guide below it ' +
+ 'that has it (`astryx docs layout side-panels`). `--depth` reads as far down the tree as you ask, from the doc alone (0) to ' +
'everything below it (all), and with it `--detail` sets how much of each doc below ' +
'shows: one line (brief, the default), its sections (compact), or all of it (full).',
fn: 'docs',
diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjs
index f4a5abfe8b..c848a51311 100644
--- a/packages/cli/clients/cli/commands/docs.test.mjs
+++ b/packages/cli/clients/cli/commands/docs.test.mjs
@@ -330,22 +330,25 @@ describe('the docs tree, one level at a time', () => {
expect(old.stderr).toContain('Unknown topic "cli-integrations"');
}, SLOW);
- it('returns docs.node as JSON, and fails a section of a namespace', async () => {
+ it('returns docs.node as JSON, and reads a section of a namespace from its guide', async () => {
const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);
expect(node).toMatchObject({
type: 'docs.node',
data: {route: 'cli', kind: 'namespace', breadcrumb: []},
});
expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);
- const section = await runCli(['docs', 'cli', 'commands', '--json']);
- expect(section.status).toBe(1);
- const error = JSON.parse(section.stdout);
- expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
- // It names the namespace's children, in the order its slots list them.
- expect(error.suggestions.map(s => s.name)).toEqual(
- node.data.slots.flatMap(slot => slot.children.map(child => child.route)),
+ const section = JSON.parse(
+ (await runCli(['docs', 'layout', 'side-panels', '--json'])).stdout,
);
- expect(error.suggestions.map(s => s.name)).toContain('cli/commands');
+ expect(section).toMatchObject({
+ type: 'docs.detail.section',
+ data: {id: 'side-panels', title: 'Side panels'},
+ });
+ const missing = await runCli(['docs', 'cli', 'zzzz-nope', '--json']);
+ expect(missing.status).toBe(1);
+ const error = JSON.parse(missing.stdout);
+ expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
+ expect(error.suggestions.map(s => s.name)).toContain('cli/integrations/quick-start');
}, SLOW);
});