👩‍⚕️ Add a {doc} role to support sphinx

.changeset/modern-ants-smell.md

@@ -0,0 +1,5 @@
+---
+'myst-roles': patch
+---
+
+Add the {doc} role to look to other documents

packages/myst-roles/src/doc.ts

@@ -0,0 +1,30 @@
+import type { RoleSpec } from 'myst-common';
+import { fileWarn, ParseTypesEnum } from 'myst-common';
+
+const REF_PATTERN = /^(.+?)<([^<>]+)>$/; // e.g. 'Labeled Document <doc>'
+
+export const docRole: RoleSpec = {
+  name: 'doc',
+  body: {
+    type: ParseTypesEnum.string,
+    required: true,
+  },
+  run(data, vfile) {
+    const body = data.body as string;
+    const match = REF_PATTERN.exec(body);
+    const [, modified, rawLabel] = match ?? [];
+    const url = rawLabel ?? body;
+    fileWarn(
+      vfile,
+      'Usage of the {doc} role is not recommended, use a markdown link to the file instead.',
+      { source: 'role:doc', note: `For {doc}\`${body}\` use [${modified || ''}](${url})` },
+    );
+    return [
+      {
+        type: 'link',
+        url,
+        children: modified ? [{ type: 'text', value: modified.trim() }] : undefined,
+      },
+    ];
+  },
+};

packages/myst-roles/src/index.ts

@@ -4,6 +4,7 @@ import { citeRole } from './cite';
 import { deleteRole } from './delete';
 import { mathRole } from './math';
 import { refRole } from './reference';
+import { docRole } from './doc';
 import { siRole } from './si';
 import { evalRole } from './inlineExpression';
 import { smallcapsRole } from './smallcaps';
@@ -18,6 +19,7 @@ export const defaultRoles = [
   deleteRole,
   mathRole,
   refRole,
+  docRole,
   siRole,
   evalRole,
   smallcapsRole,
@@ -31,6 +33,7 @@ export { citeRole } from './cite';
 export { deleteRole } from './delete';
 export { mathRole } from './math';
 export { refRole } from './reference';
+export { docRole } from './doc';
 export { siRole } from './si';
 export { smallcapsRole } from './smallcaps';
 export { subscriptRole } from './subscript';