docs: migrate to Docusaurus (callstack#3614)

Co-authored-by: lukewalczak <[email protected]>
Co-authored-by: Andriy Tsaryov <[email protected]>
Co-authored-by: Yaman KATBY <[email protected]>

Author: 4 people

Diff for: .circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 executors:
   default:
     docker:
-      - image: circleci/node:16
+      - image: cimg/node:16.18.0
     working_directory: ~/react-native-paper
 
 commands:
@@ -104,10 +104,11 @@ jobs:
       - run:
           name: Build docs
           command: |
+            export DOCUSAURUS_BASE_URL="/output/job/$CIRCLE_WORKFLOW_JOB_ID/artifacts/$CIRCLE_NODE_INDEX/docs/"
             cd docs && yarn build && cd ..
             bash .circleci/comment-artifacts.sh
       - store_artifacts:
-          path: docs/dist
+          path: docs/build
           destination: docs
 
   deploy-docs:
@@ -148,4 +149,5 @@ workflows:
       - deploy-docs:
           filters:
             branches:
-              only: main
+              only:
+                - main

Diff for: .circleci/deploy-docs.sh

@@ -9,7 +9,14 @@ DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SOURCE_BRANCH="main"
 TARGET_BRANCH="gh-pages"
 
-cd $DIR/../docs
+git checkout $SOURCE_BRANCH
+
+cd $DIR/..
+
+# Install React Native Paper dependencies for examples
+yarn
+
+cd docs
 
 # Save some useful information
 REPO=`git config remote.origin.url`
@@ -25,34 +32,19 @@ cd ..
 
 # Clean existing dist/ contents
 rm -rf dist/**/* || :
-rm -f dist/*.{html,css,js,json,map} || :
+rm -f dist/*.{html,css,js,json,map,xml} || :
 rmdir dist/* || :
 
 # Run our build script.
 yarn
 yarn build
 
-# Build the docs for 1.0
-git checkout 1.0
-yarn
-yarn build
+# Move the built docs to cloned `gh-pages` directory
+cp -R build/. dist
 
-# Build the docs for 2.0
-git checkout 2.0
-yarn
-yarn build
-
-# Build the docs for 3.0
-git checkout 3.0
-yarn
-yarn build
-
-# Build the docs for 4.0
-git checkout 4.0
-yarn
-yarn build
+rm -rf build
 
-# Push the built docs
+# Change directory to the one using `gh-pages` branch
 cd dist
 
 # Configure git.

Diff for: .eslintignore

@@ -2,6 +2,9 @@ node_modules/
 flow-typed/
 coverage/
 docs/dist/
+docs/build/
+docs/public/
+docs/static/
 web-build/
 testSetup.js
 

Diff for: docs/.babelrc

@@ -0,0 +1,15 @@
+{
+  "extends": "../.eslintrc",
+
+  "settings": {
+    "import/core-modules": ["react-native-paper"]
+  },
+
+  "rules": {
+    "react/prop-types": "off",
+    "import/no-unresolved": [
+      2,
+      {"ignore": ["^@docusaurus"]}
+    ]
+  }
+}

Diff for: docs/.eslintrc

@@ -1,2 +1,27 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# component-docs-plugin
+docs/components
+
+# legacy
 dist/
 .linaria-cache/

Diff for: docs/.gitignore

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

Diff for: docs/README.md

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: ['@docusaurus/core/lib/babel/preset'],
+};

Diff for: docs/assets/screenshots/list-image.png

@@ -0,0 +1,28 @@
+const config = require('../docusaurus.config');
+
+const { baseUrl } = config;
+
+function generatePageMDX(doc, link) {
+  const description = doc.description
+    .replace(/<\/br>/g, '')
+    .replace(/style="[a-zA-Z0-9:;.\s()\-,]*"/gi, '')
+    .replace(/src="screenshots/g, `src="${baseUrl}screenshots`);
+
+  const mdx = `
+---
+title: ${doc.title}
+---
+
+import PropTable from '@site/src/components/PropTable.tsx';
+
+${description}
+
+## Props
+
+<PropTable link="${link}" />
+`;
+
+  return mdx.slice(1);
+}
+
+module.exports = generatePageMDX;

Diff for: docs/assets/showcase/kurogahome.png

@@ -0,0 +1,92 @@
+const {
+  default: parseComponentDocs,
+} = require('component-docs/dist/parsers/component');
+const fs = require('fs');
+const path = require('path');
+
+const generatePageMDX = require('./generatePageMDX');
+
+const pluginName = 'component-docs-plugin';
+
+async function componentsPlugin(_, options) {
+  const { docsRootDir, libsRootDir, pages } = options;
+
+  function clean() {
+    fs.rmSync(docsRootDir, { recursive: true, force: true });
+  }
+
+  function createCategory(label, dir = '.') {
+    const categoryJSON = JSON.stringify({ label }, undefined, 2);
+    const docsCategoryDir = path.join(docsRootDir, dir);
+    if (!fs.existsSync(docsCategoryDir)) {
+      fs.mkdirSync(docsCategoryDir);
+    }
+    fs.writeFileSync(
+      path.join(docsCategoryDir, `_category_.json`),
+      categoryJSON
+    );
+  }
+
+  function createPageForComponent(targetArray, source) {
+    const [item, subitem] = targetArray;
+    const target = subitem ? `${item}/${subitem}` : item;
+    const targetPath = target + '.mdx';
+    const sourcePath = source + '.tsx';
+
+    // Parse component using component-docs.
+    const doc = parseComponentDocs(path.join(libsRootDir, sourcePath), {
+      root: libsRootDir,
+    });
+
+    // Create directory for the output mdx file.
+    fs.mkdirSync(
+      path.join(docsRootDir, targetPath).split('/').slice(0, -1).join('/'),
+      { recursive: true }
+    );
+
+    // Generate and write mdx file.
+    fs.writeFileSync(
+      path.join(docsRootDir, targetPath),
+      generatePageMDX(doc, source)
+    );
+
+    return doc;
+  }
+
+  return {
+    name: pluginName,
+    async loadContent() {
+      // Clean up docs directory.
+      clean();
+      // Create root components category.
+      createCategory('Components', '.');
+
+      const docs = {};
+
+      for (const item in pages) {
+        if (typeof pages[item] === 'string') {
+          const doc = createPageForComponent([item], pages[item]);
+          docs[pages[item]] = doc;
+        } else {
+          for (const subitem in pages[item]) {
+            const doc = createPageForComponent(
+              [item, subitem],
+              pages[item][subitem]
+            );
+            docs[pages[item][subitem]] = doc;
+          }
+        }
+      }
+
+      return docs;
+    },
+    async contentLoaded({ content: docs, actions }) {
+      // Store component docs global data so it can be used in `PropsTable` component.
+      actions.setGlobalData({
+        docs,
+      });
+    },
+  };
+}
+
+module.exports = componentsPlugin;