Fix and extend the auto doc-gen script

.gitignore

@@ -13,3 +13,5 @@ website/i18n/*
 !website/i18n/en.json
 
 .nvmrc
+website/scripts/sync-api-docs/generatedComponentApiDocs.js
+website/scripts/sync-api-docs/extracted.json

website/package.json

@@ -17,9 +17,9 @@
     "version": "docusaurus-version",
     "rename-version": "docusaurus-rename-version",
     "ci-check": "yarn prettier:diff && node image-check.js",
-    "format:source": "prettier --write \"{core/**/*.js,static/js/**/*.js}\"",
+    "format:source": "prettier --write \"{core/**/*.js,scripts/**/*.js,static/js/**/*.js}\"",
     "format:markdown": "prettier --write \"{../docs/*.md,versioned_docs/**/*.md,blog/**/*.md}\"",
-    "nit:source": "prettier --list-different \"{core/**/*.js,static/js/**/*.js}\"",
+    "nit:source": "prettier --list-different \"{core/**/*.js,scripts/**/*.js,static/js/**/*.js}\"",
     "nit:markdown": "prettier --list-different \"{../docs/*.md,versioned_docs/**/*.md,blog/**/*.md}\"",
     "prettier": "yarn format:source && yarn format:markdown",
     "prettier:diff": "yarn nit:source",
@@ -28,6 +28,7 @@
     "test": "yarn build",
     "lint": "cd ../ && alex .",
     "lintv": "cd ../ && alex",
+    "sync:docs": "node scripts/sync-api-docs/sync-api-docs ../../react-native",
     "update-lock": "npx yarn-deduplicate && npx optimize-yarn-lock"
   },
   "husky": {
@@ -41,6 +42,7 @@
     "remarkable": "^2.0.1"
   },
   "devDependencies": {
+    "@motiz88/react-native-docgen": "0.0.3",
     "alex": "^8.2.0",
     "front-matter": "^4.0.2",
     "fs-extra": "^9.0.1",
@@ -50,6 +52,8 @@
     "node-fetch": "^2.6.0",
     "path": "^0.12.7",
     "prettier": "1.16.4",
-    "pretty-quick": "^1.11.1"
+    "pretty-quick": "^1.11.1",
+    "react-docgen-markdown-renderer": "^2.1.3",
+    "tokenize-comment": "^3.0.1"
   }
 }

website/scripts/sync-api-docs/extractDocsFromRN.js

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+'use strict';
+
+const fs = require('fs-extra');
+const glob = require('glob');
+const path = require('path');
+const reactDocs = require('@motiz88/react-native-docgen');
+
+const GENERATE_ANNOTATION = '@' + 'generate-docs';
+
+module.exports = extractDocsFromRN;
+
+async function extractDocsFromRN(rnRoot) {
+  // TODO: make implementation async
+
+  const allComponentFiles = glob.sync(
+    path.join(rnRoot, '/Libraries/{Components,Image,}/**/*.js'),
+    {
+      nodir: true,
+      absolute: true,
+    }
+  );
+
+  const docs = [];
+
+  for (const file of allComponentFiles) {
+    const contents = fs.readFileSync(file, {encoding: 'utf-8'});
+    if (!contents.includes(GENERATE_ANNOTATION)) {
+      continue;
+    }
+
+    console.log(file);
+
+    const result = reactDocs.parse(
+      contents,
+      reactDocs.resolver.findExportedComponentDefinition,
+      reactDocs.defaultHandlers.filter(
+        handler => handler !== reactDocs.handlers.propTypeCompositionHandler
+      ),
+      {filename: file}
+    );
+
+    docs.push({
+      file,
+      component: cleanComponentResult(result),
+    });
+  }
+
+  // Make sure output is JSON-safe
+  const docsSerialized = JSON.parse(JSON.stringify(docs));
+  await fs.writeFile(
+    path.join(__dirname, 'extracted.json'),
+    JSON.stringify(docsSerialized, null, 2),
+    'utf8'
+  );
+  return docsSerialized;
+}
+
+function cleanComponentResult(component) {
+  return {
+    ...component,
+    methods: component.methods.filter(method => !method.name.startsWith('_')),
+  };
+}

website/scripts/sync-api-docs/generateMarkdown.js

@@ -0,0 +1,269 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const tokenizeComment = require('tokenize-comment');
+const {
+  formatMultiplePlatform,
+  maybeLinkifyType,
+  maybeLinkifyTypeName,
+  formatTypeColumn,
+  formatDefaultColumn,
+} = require('./propFormatter');
+
+// Formats an array of rows as a Markdown table
+function generateTable(rows) {
+  const colWidths = new Map();
+  for (const row of rows) {
+    for (const col of Object.keys(row)) {
+      colWidths.set(
+        col,
+        Math.max(colWidths.get(col) || col.length, String(row[col]).length)
+      );
+    }
+  }
+  if (!colWidths.size) {
+    return '';
+  }
+  let header = '|',
+    divider = '|';
+  for (const [col, width] of colWidths) {
+    header += ' ' + col.padEnd(width + 1) + '|';
+    divider += ' ' + '-'.repeat(width) + ' ' + '|';
+  }
+
+  let result = header + '\n' + divider + '\n';
+  for (const row of rows) {
+    result += '|';
+    for (const [col, width] of colWidths) {
+      result += ' ' + String(row[col] || '').padEnd(width + 1) + '|';
+    }
+    result += '\n';
+  }
+  return result;
+}
+
+// Formats information about a prop
+function generateProp(propName, prop) {
+  const infoTable = generateTable([
+    {
+      Type: formatTypeColumn(prop),
+      ...formatDefaultColumn(prop),
+    },
+  ]);
+
+  return (
+    '### ' +
+    (prop.required ? '<div class="label required basic">Required</div>' : '') +
+    '`' +
+    propName +
+    '`' +
+    (prop.rnTags && prop.rnTags.platform
+      ? formatMultiplePlatform(prop.rnTags.platform)
+      : '') +
+    '\n' +
+    '\n' +
+    (prop.description ? prop.description + '\n\n' : '') +
+    infoTable
+  );
+}
+
+// Formats information about a prop
+function generateMethod(method, component) {
+  const infoTable = generateTable([
+    {
+      ...(method.rnTags && method.rnTags.platform
+        ? {Platform: formatPlatformName(method.rnTags.platform)}
+        : {}),
+    },
+  ]);
+
+  return (
+    '### `' +
+    method.name +
+    '()`' +
+    '\n' +
+    '\n' +
+    generateMethodSignatureBlock(method, component) +
+    (method.description ? method.description + '\n\n' : '') +
+    generateMethodSignatureTable(method, component) +
+    infoTable
+  ).trim();
+}
+
+function lowerFirst(s) {
+  return s[0].toLowerCase() + s.slice(1);
+}
+
+function generateMethodSignatureBlock(method, component) {
+  return (
+    '```jsx\n' +
+    (method.modifiers.includes('static')
+      ? component.displayName + '.'
+      : lowerFirst(component.displayName + '.')) +
+    method.name +
+    '(' +
+    method.params
+      .map(param => (param.optional ? `[${param.name}]` : param.name))
+      .join(', ') +
+    ');' +
+    '\n' +
+    '```\n\n'
+  );
+}
+
+function generateMethodSignatureTable(method, component) {
+  if (!method.params.length) {
+    return '';
+  }
+  return (
+    '**Parameters:**\n\n' +
+    generateTable(
+      method.params.map(param => ({
+        Name: param.name,
+        Type: param.type ? maybeLinkifyType(param.type) : '',
+        Required: param.optional ? 'No' : 'Yes',
+        Description: param.description,
+      }))
+    )
+  );
+}
+
+// Formats information about props
+function generateProps({props, composes}) {
+  if (!props || !Object.keys(props).length) {
+    return '';
+  }
+
+  return (
+    '## Props' +
+    '\n' +
+    '\n' +
+    (composes && composes.length
+      ? composes
+          .map(parent => 'Inherits ' + maybeLinkifyTypeName(parent) + '.')
+          .join('\n\n') + '\n\n'
+      : '') +
+    Object.keys(props)
+      .sort((a, b) => a.localeCompare(b))
+      .sort((a, b) => props[b].required - props[a].required)
+      .map(function(propName) {
+        return generateProp(propName, props[propName]);
+      })
+      .join('\n\n---\n\n')
+  );
+}
+
+function generateMethods(component) {
+  const {methods} = component;
+  if (!methods || !methods.length) {
+    return '';
+  }
+
+  return (
+    '## Methods' +
+    '\n' +
+    '\n' +
+    [...methods]
+      .sort((a, b) =>
+        a.name.localeCompare(
+          b.name /* TODO @nocommit what's a neutral locale */
+        )
+      )
+      .map(function(method) {
+        return generateMethod(method, component);
+      })
+      .join('\n\n---\n\n')
+  );
+}
+
+// Generates a Docusaurus header for a component page
+function generateHeader({id, title}) {
+  return (
+    '---' + '\n' + 'id: ' + id + '\n' + 'title: ' + title + '\n' + '---' + '\n'
+  );
+}
+
+// Function to process example contained description
+function preprocessDescription(desc) {
+  // Playground tabs for the class and functional components
+  const playgroundTab = `<div class="toggler">
+    <ul role="tablist" class="toggle-syntax">
+      <li id="functional" class="button-functional" aria-selected="false" role="tab" tabindex="0" aria-controls="functionaltab" onclick="displayTabs('syntax', 'functional')">
+        Function Component Example
+      </li>
+      <li id="classical" class="button-classical" aria-selected="false" role="tab" tabindex="0" aria-controls="classicaltab" onclick="displayTabs('syntax', 'classical')">
+        Class Component Example
+      </li>
+    </ul>
+  </div>`;
+
+  //Blocks for different syntax sections
+  const functionalBlock = `<block class='functional syntax' />`;
+  const classBlock = `<block class='classical syntax' />`;
+  const endBlock = `<block class='endBlock syntax' />`;
+
+  desc = desc
+    .split('\n')
+    .map(line => {
+      return line.replace(/  /, '');
+    })
+    .join('\n');
+
+  const descriptionTokenized = tokenizeComment(desc);
+  // Tabs counter for examples
+  let tabs = 0;
+  descriptionTokenized.examples.map(item => {
+    const matchSnackPlayer = item.language.match(/(SnackPlayer name=).*/g);
+    if (matchSnackPlayer) {
+      const matchClassComp = matchSnackPlayer[0].match(
+        /Class%20Component%20Example/
+      );
+      const matchFuncComp = matchSnackPlayer[0].match(
+        /Function%20Component%20Example/
+      );
+      if (matchClassComp || matchFuncComp) tabs++;
+    }
+  });
+
+  if (tabs === 2) {
+    const wrapper = `${playgroundTab}\n\n${functionalBlock}\n\n${
+      descriptionTokenized.examples[0].raw
+    }\n\n${classBlock}\n\n${
+      descriptionTokenized.examples[1].raw
+    }\n\n${endBlock}`;
+    return (
+      descriptionTokenized.description +
+      `\n## Example\n` +
+      wrapper +
+      '\n' +
+      descriptionTokenized?.footer
+    );
+  } else {
+    return (
+      desc.substr(0, desc.search('```SnackPlayer')) +
+      '\n' +
+      '\n## Example\n' +
+      '\n' +
+      desc.substr(desc.search('```SnackPlayer'))
+    );
+  }
+}
+
+function generateMarkdown({id, title}, component) {
+  const markdownString =
+    generateHeader({id, title}) +
+    '\n' +
+    preprocessDescription(component.description) +
+    '\n\n' +
+    '---\n\n' +
+    '# Reference\n\n' +
+    generateProps(component) +
+    generateMethods(component);
+
+  return markdownString.replace(/\n{3,}/g, '\n\n');
+}
+
+module.exports = generateMarkdown;