Skip to content

fix(parser): transform man pages #349

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions src/generators/metadata/utils/parse.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ export const parseApiDoc = ({ file, tree }) => {
addYAMLMetadata,
updateMarkdownLink,
updateTypeReference,
updateUnixManualReference,
updateLinkReference,
addStabilityMetadata,
} = createQueries();
Expand Down Expand Up @@ -127,6 +128,13 @@ export const parseApiDoc = ({ file, tree }) => {
updateTypeReference(node, parent)
);

// Visits all Unix manual references, and replaces them with links
visit(
subTree,
createQueries.UNIST.isTextWithUnixManual,
(node, _, parent) => updateUnixManualReference(node, parent)
);

// Removes already parsed items from the subtree so that they aren't included in the final content
remove(subTree, [createQueries.UNIST.isYamlNode]);

Expand Down
3 changes: 3 additions & 0 deletions src/utils/parser/constants.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
// This is the base URL of the MDN Web documentation
export const DOC_MDN_BASE_URL = 'https://developer.mozilla.org/en-US/docs/Web/';

// This is the base URL of the Man7 documentation
export const DOC_MAN_BASE_URL = 'http://man7.org/linux/man-pages/man';

// This is the base URL for the MDN JavaScript documentation
export const DOC_MDN_BASE_URL_JS = `${DOC_MDN_BASE_URL}JavaScript/`;

Expand Down
16 changes: 16 additions & 0 deletions src/utils/parser/index.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import {
DOC_TYPES_MAPPING_NODE_MODULES,
DOC_TYPES_MAPPING_OTHER,
DOC_TYPES_MAPPING_PRIMITIVES,
DOC_MAN_BASE_URL,
} from './constants.mjs';
import createQueries from '../queries/index.mjs';

Expand Down Expand Up @@ -44,6 +45,21 @@ export const normalizeYamlSyntax = yamlContent => {
.replace(/^[\r\n]+|[\r\n]+$/g, ''); // Remove initial and final line breaks
};

/**
* @param {string} text The inner text
* @param {string} command The manual page
* @param {string} sectionNumber The manual section
* @param {string} sectionLetter The manual section number
*/
export const transformUnixManualToLink = (
text,
command,
sectionNumber,
sectionLetter = ''
) => {
return `[\`${text}\`](${DOC_MAN_BASE_URL}${sectionNumber}/${command}.${sectionNumber}${sectionLetter}.html)`;
};

/**
* This method replaces plain text Types within the Markdown content into Markdown links
* that link to the actual relevant reference for such type (either internal or external link)
Expand Down
39 changes: 30 additions & 9 deletions src/utils/queries/index.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import {
parseHeadingIntoMetadata,
parseYAMLIntoMetadata,
transformTypeToReferenceLink,
transformUnixManualToLink,
} from '../parser/index.mjs';
import { getRemark } from '../remark.mjs';
import { transformNodesToString } from '../unist.mjs';
Expand Down Expand Up @@ -64,18 +65,17 @@ const createQueries = () => {
};

/**
* Updates a Markdown text containing an API type reference
* into a Markdown link referencing to the correct API docs
* Updates a reference
*
* @param {import('@types/mdast').Text} node A Markdown link node
* @param {import('@types/mdast').Text} node The current node
* @param {import('@types/mdast').Parent} parent The parent node
* @param {string|RegExp} query The search query
* @param {Function} transformer The function to transform the reference
*
*/
const updateTypeReference = (node, parent) => {
const updateReferences = (query, transformer, node, parent) => {
const replacedTypes = node.value
.replace(
createQueries.QUERIES.normalizeTypes,
transformTypeToReferenceLink
)
.replace(query, transformer)
// Remark doesn't handle leading / trailing spaces, so replace them with
// HTML entities.
.replace(/^\s/, ' ')
Expand Down Expand Up @@ -172,7 +172,20 @@ const createQueries = () => {
addYAMLMetadata,
setHeadingMetadata,
updateMarkdownLink,
updateTypeReference,
/** @param {Array<import('@types/mdast').Node>} args */
updateTypeReference: (...args) =>
updateReferences(
createQueries.QUERIES.normalizeTypes,
transformTypeToReferenceLink,
...args
),
/** @param {Array<import('@types/mdast').Node>} args */
updateUnixManualReference: (...args) =>
updateReferences(
createQueries.QUERIES.unixManualPage,
transformUnixManualToLink,
...args
),
updateLinkReference,
addStabilityMetadata,
updateStabilityPrefixToLink,
Expand All @@ -195,6 +208,8 @@ createQueries.QUERIES = {
stabilityIndexPrefix: /Stability: ([0-5])/,
// ReGeX for retrieving the inner content from a YAML block
yamlInnerContent: /^<!--[ ]?(?:YAML([\s\S]*?)|([ \S]*?))?[ ]?-->/,
// ReGeX for finding references to Unix manuals
unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/g,
};

createQueries.UNIST = {
Expand All @@ -217,6 +232,12 @@ createQueries.UNIST = {
*/
isTextWithType: ({ type, value }) =>
type === 'text' && createQueries.QUERIES.normalizeTypes.test(value),
/**
* @param {import('@types/mdast').Text} text
* @returns {boolean}
*/
isTextWithUnixManual: ({ type, value }) =>
type === 'text' && createQueries.QUERIES.unixManualPage.test(value),
/**
* @param {import('@types/mdast').Html} html
* @returns {boolean}
Expand Down
Loading