refactor: dox

build/flecks.yml

@@ -5,7 +5,14 @@
 '@flecks/create:./packages/create-fleck': {}
 '@flecks/db:./packages/db': {}
 '@flecks/docker:./packages/docker': {}
-'@flecks/dox:./packages/dox': {}
+'@flecks/dox:./packages/dox':
+  rewriteFilenames:
+    -
+      - '@flecks\/([^/]+)\/(.*)'
+      - '[@flecks/**$1**<span style={{fontSize: "80%"}}>&#8203;`/$2`</span>](https://github.com/cha0s/flecks/tree/master/packages/$1/$2)'
+    -
+      - '\((.*):([0-9]+):[0-9]+\)'
+      - '($1#L$2)'
 '@flecks/electron:./packages/electron': {}
 '@flecks/fleck:./packages/fleck': {}
 '@flecks/governor:./packages/governor': {}

package.json

@@ -9,8 +9,8 @@
   "scripts": {
     "build": "lerna run build",
     "clean": "lerna exec yarn clean",
-    "dox:gh-pages": "flecks dox docusaurus -r '@flecks\/([^/]+)\/(.*)=[@flecks/**$1**/$2](https://github.com/cha0s/flecks/tree/master/packages/$1/$2)' -r '\\((.*):([0-9]+):[0-9]+\\)=($1#L$2)' && cd website && DOCUSAURUS_GENERATED_FILES_DIR_NAME=node_modules/.cache/docusaurus node_modules/.bin/docusaurus build --out-dir ../dox-tmp && cd .. && rm -rf dox/* && mv dox-tmp/* dox && rmdir dox-tmp",
+    "dox:gh-pages": "flecks dox docusaurus && cd website && DOCUSAURUS_GENERATED_FILES_DIR_NAME=node_modules/.cache/docusaurus node_modules/.bin/docusaurus build --out-dir ../dox-tmp && cd .. && rm -rf dox/* && mv dox-tmp/* dox && rmdir dox-tmp",
-    "dox": "flecks dox docusaurus -r '@flecks\/([^/]+)\/(.*)=[@flecks/**$1**/$2](https://github.com/cha0s/flecks/tree/master/packages/$1/$2)' -r '\\((.*):([0-9]+):[0-9]+\\)=($1#L$2)' && cd website && DOCUSAURUS_GENERATED_FILES_DIR_NAME=node_modules/.cache/docusaurus node_modules/.bin/docusaurus",
+    "dox": "flecks dox docusaurus && cd website && DOCUSAURUS_GENERATED_FILES_DIR_NAME=node_modules/.cache/docusaurus node_modules/.bin/docusaurus",
     "lint": "lerna run lint",
     "publish": "lerna publish --conventional-commits --contents=dist --registry https://registry.npmjs.org",
     "test": "lerna exec 'yarn && yarn test'"

packages/build/build/flecks.hooks.js

@@ -36,7 +36,7 @@ export const hooks = {
   '@flecks/build.extensions': () => ['.coffee'],
 
   /**
-   * Register build files.
+   * Register build files. See [the build files page](./build-files) for more details.
    */
   '@flecks/build.files': () => [
     /**

packages/core/build/flecks.hooks.js

@@ -8,7 +8,7 @@ export const hooks = {
   }),
 
   /**
-   * Define configuration.
+   * Define configuration. See [the configuration page](./config) for more details.
    */
   '@flecks/core.config': () => ({
     whatever: 'configuration',

packages/dox/build/commands.js

@@ -1,9 +1,10 @@
-const {mkdir, writeFile} = require('fs/promises');
+const {mkdir, readFile, writeFile} = require('fs/promises');
 const {join, relative, resolve} = require('path');
 
 const {
   generateDocusaurus,
   generateJson,
+  generateDocusaurusStyle,
 } = require('./generate');
 
 const {
@@ -33,7 +34,11 @@ module.exports = (program, flecks) => {
       let output;
       const json = await generateJson(flecks);
       const pairs = rewriteFilenames
-        .map((pair) => pair.split('='))
+        .map((pair) => {
+          const index = pair.indexOf('=');
+          return [pair.slice(0, index), pair.slice(index + 1)];
+        })
+        .concat(flecks.get('@flecks/dox.rewriteFilenames'))
         .map(([from, to]) => [new RegExp(from, 'g'), to]);
       const rewrite = (array) => (
         array.map(
@@ -66,6 +71,7 @@ module.exports = (program, flecks) => {
             Object.entries(generateDocusaurus(json))
               .map(([type, page]) => [`${type}.mdx`, page]),
           );
+          output['dox.module.css'] = await generateDocusaurusStyle();
           break;
         case 'json':
           output = Object.fromEntries(

packages/dox/build/flecks.bootstrap.js

@@ -2,4 +2,10 @@ const commands = require('./commands');
 
 exports.hooks = {
   '@flecks/build.commands': commands,
+  '@flecks/core.config': () => ({
+    /**
+     * Pattern pairs used to rewrite filenames in generated documentation.
+     */
+    rewriteFilenames: [],
+  }),
 };

packages/dox/build/generate.js

@@ -88,6 +88,8 @@ exports.generateDocusaurusHookPage = (hooks) => {
   source.push('description: All the hooks in this project.');
   source.push('---');
   source.push('');
+  source.push("import styles from './dox.module.css';");
+  source.push('');
   source.push('This page documents all the hooks in this project.');
   source.push('');
   Object.entries(hooks)
@@ -121,32 +123,55 @@ exports.generateDocusaurusHookPage = (hooks) => {
         });
         source.push('');
       }
-      if (implementations.length > 0) {
+      if (implementations.length > 0 || invocations.length > 0) {
-        source.push('<details>');
+        source.push('<div className={styles.hooks}>');
-        source.push('<summary>Implementations</summary>');
+        if (implementations.length > 0) {
-        source.push('<ul>');
+          source.push('<div>');
-        implementations.forEach(({filename}) => {
+          source.push('<h3>Implementations</h3>');
-          source.push(`<li>${filename}</li>`);
+          implementations.forEach(({filename}) => {
-        });
+            source.push(`<div>${filename}</div>`);
-        source.push('</ul>');
+          });
-        source.push('</details>');
+          source.push('</div>');
-        source.push('');
+        }
-      }
+        if (invocations.length > 0) {
-      if (invocations.length > 0) {
+          source.push('<div>');
-        source.push('<details>');
+          source.push('<h3>Invocations</h3>');
-        source.push('<summary>Invocations</summary>');
+          invocations.forEach(({filename, type}) => {
-        source.push('<ul>');
+            source.push(`<div>${filename} (\`${type}\`)</div>`);
-        invocations.forEach(({filename, type}) => {
+          });
-          source.push(`<li>${filename} (\`${type}\`)</li>`);
+          source.push('</div>');
-        });
+        }
-        source.push('</ul>');
+        source.push('</div>');
-        source.push('</details>');
-        source.push('');
       }
     });
   return source.join('\n');
 };
 
+exports.generateDocusaurusStyle = () => `
+.hooks > div {
+  margin-bottom: var(--ifm-heading-margin-bottom);
+}
+.hooks > div code {
+  white-space: nowrap;
+}
+@media screen and (min-width: 641px) {
+  .hooks {
+    display: flex;
+  }
+  .hooks > div:first-child {
+    width: 50%;
+  }
+  .hooks > div:last-child {
+    padding-left: var(--ifm-spacing-horizontal);
+    width: 50%;
+  }
+  .hooks > div:only-child {
+    padding-left: 0;
+    width: 100%;
+  }
+}
+`;
+
 exports.generateDocusaurusTodoPage = (todos) => {
   const source = [];
   source.push('---');

packages/dox/package.json

@@ -18,9 +18,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
+  "files": [],
-    "website"
-  ],
   "dependencies": {
     "@babel/core": "^7.17.2",
     "@babel/traverse": "^7.17.0",

packages/dox/website/docs/.gitignore

@@ -1,2 +0,0 @@
-# This ignores the automatically-generated `flecks` subfolder.
-/flecks

packages/dox/website/docs/introduction.mdx

@@ -1,9 +0,0 @@
----
-description: This project was built with flecks and is totally awesome!
-slug: /
----
-
-# Introduction
-
-⚡️ Welcome to your documentation website! From here, you will want to consult the
-[Docusaurus](https://docusaurus.io/) documentation to learn how to build this website out!

packages/dox/website/docusaurus.config.js

@@ -1,21 +0,0 @@
-// @ts-check
-// `@type` JSDoc annotations allow editor autocompletion and type checking
-// (when paired with `@ts-check`).
-// There are various equivalent ways to declare your Docusaurus config.
-// See: https://docusaurus.io/docs/api/docusaurus-config
-
-// eslint-disable-next-line import/no-extraneous-dependencies
-const {configDefaults} = require('@flecks/dox/build/docusaurus');
-
-module.exports = async function flecksDocusaurus() {
-  const defaults = configDefaults();
-  /** @type {import('@docusaurus/types').Config} */
-  const config = {
-    ...defaults,
-    title: 'My documentation website',
-    tagline: 'built with flecks',
-    url: 'http://localhost',
-    baseUrl: '/',
-  };
-  return config;
-};

packages/dox/website/pages/index.jsx

@@ -1,41 +0,0 @@
-import clsx from 'clsx';
-import Link from '@docusaurus/Link';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import Layout from '@theme/Layout';
-
-import Heading from '@theme/Heading';
-import styles from './index.module.css';
-
-function HomepageHeader() {
-  const {siteConfig} = useDocusaurusContext();
-  return (
-    <header className={clsx('hero hero--primary', styles.heroBanner)}>
-      <div className="container">
-        <Heading as="h1" className="hero__title">
-          {siteConfig.title}
-        </Heading>
-        <p className="hero__subtitle">{siteConfig.tagline}</p>
-        <div className={styles.buttons}>
-          <Link
-            className="button button--secondary button--lg"
-            to="/docs"
-          >
-            Your documentation here
-          </Link>
-        </div>
-      </div>
-    </header>
-  );
-}
-
-export default function Home() {
-  const {siteConfig} = useDocusaurusContext();
-  return (
-    <Layout
-      title={`Hello from ${siteConfig.title}`}
-      description="Description will go into a meta tag in <head />"
-    >
-      <HomepageHeader />
-    </Layout>
-  );
-}

packages/dox/website/pages/index.module.css

@@ -1,23 +0,0 @@
-/**
- * CSS files with the .module.css suffix will be treated as CSS modules
- * and scoped locally.
- */
-
-.heroBanner {
-  padding: 4rem 0;
-  text-align: center;
-  position: relative;
-  overflow: hidden;
-}
-
-@media screen and (max-width: 996px) {
-  .heroBanner {
-    padding: 2rem;
-  }
-}
-
-.buttons {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}

packages/dox/website/sidebars.js

@@ -1,5 +0,0 @@
-export default {
-  sidebar: [
-    'introduction',
-  ],
-};

website/sidebars.js

@@ -59,7 +59,7 @@ export default {
         'flecks/hooks',
         'flecks/config',
         'flecks/build-files',
-        'flecks/todo',
+        'flecks/todos',
       ],
     },
   ],