diff --git a/build/flecks.yml b/build/flecks.yml index d665d80..9e5bcd3 100644 --- a/build/flecks.yml +++ b/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**​`/$2`](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': {} diff --git a/package.json b/package.json index ef925a3..33943c8 100644 --- a/package.json +++ b/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": "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: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 && 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'" diff --git a/packages/build/build/flecks.hooks.js b/packages/build/build/flecks.hooks.js index d06ce67..80672b5 100644 --- a/packages/build/build/flecks.hooks.js +++ b/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': () => [ /** diff --git a/packages/core/build/flecks.hooks.js b/packages/core/build/flecks.hooks.js index 895cdcb..5780b9d 100644 --- a/packages/core/build/flecks.hooks.js +++ b/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', diff --git a/packages/dox/build/commands.js b/packages/dox/build/commands.js index 9d37af0..096fe82 100644 --- a/packages/dox/build/commands.js +++ b/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( diff --git a/packages/dox/build/flecks.bootstrap.js b/packages/dox/build/flecks.bootstrap.js index cb7810c..e7cb359 100644 --- a/packages/dox/build/flecks.bootstrap.js +++ b/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: [], + }), }; diff --git a/packages/dox/build/generate.js b/packages/dox/build/generate.js index 157982d..904d161 100644 --- a/packages/dox/build/generate.js +++ b/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) { - source.push('
'); - source.push('Implementations'); - source.push(''); - source.push('
'); - source.push(''); - } - if (invocations.length > 0) { - source.push('
'); - source.push('Invocations'); - source.push(''); - source.push('
'); - source.push(''); + if (implementations.length > 0 || invocations.length > 0) { + source.push('
'); + if (implementations.length > 0) { + source.push('
'); + source.push('

Implementations

'); + implementations.forEach(({filename}) => { + source.push(`
${filename}
`); + }); + source.push('
'); + } + if (invocations.length > 0) { + source.push('
'); + source.push('

Invocations

'); + invocations.forEach(({filename, type}) => { + source.push(`
${filename} (\`${type}\`)
`); + }); + source.push('
'); + } + 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('---'); diff --git a/packages/dox/package.json b/packages/dox/package.json index 64d284b..c710edc 100644 --- a/packages/dox/package.json +++ b/packages/dox/package.json @@ -18,9 +18,7 @@ "publishConfig": { "access": "public" }, - "files": [ - "website" - ], + "files": [], "dependencies": { "@babel/core": "^7.17.2", "@babel/traverse": "^7.17.0", diff --git a/packages/dox/website/docs/.gitignore b/packages/dox/website/docs/.gitignore deleted file mode 100644 index 0cce234..0000000 --- a/packages/dox/website/docs/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# This ignores the automatically-generated `flecks` subfolder. -/flecks diff --git a/packages/dox/website/docs/introduction.mdx b/packages/dox/website/docs/introduction.mdx deleted file mode 100644 index e2dbfe0..0000000 --- a/packages/dox/website/docs/introduction.mdx +++ /dev/null @@ -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! diff --git a/packages/dox/website/docusaurus.config.js b/packages/dox/website/docusaurus.config.js deleted file mode 100644 index e2e2397..0000000 --- a/packages/dox/website/docusaurus.config.js +++ /dev/null @@ -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; -}; diff --git a/packages/dox/website/pages/index.jsx b/packages/dox/website/pages/index.jsx deleted file mode 100644 index 4c693d7..0000000 --- a/packages/dox/website/pages/index.jsx +++ /dev/null @@ -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 ( -
-
- - {siteConfig.title} - -

{siteConfig.tagline}

-
- - Your documentation here - -
-
-
- ); -} - -export default function Home() { - const {siteConfig} = useDocusaurusContext(); - return ( - - - - ); -} diff --git a/packages/dox/website/pages/index.module.css b/packages/dox/website/pages/index.module.css deleted file mode 100644 index 9f71a5d..0000000 --- a/packages/dox/website/pages/index.module.css +++ /dev/null @@ -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; -} diff --git a/packages/dox/website/sidebars.js b/packages/dox/website/sidebars.js deleted file mode 100644 index e1a6998..0000000 --- a/packages/dox/website/sidebars.js +++ /dev/null @@ -1,5 +0,0 @@ -export default { - sidebar: [ - 'introduction', - ], -}; diff --git a/website/sidebars.js b/website/sidebars.js index a157b7a..d81339c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -59,7 +59,7 @@ export default { 'flecks/hooks', 'flecks/config', 'flecks/build-files', - 'flecks/todo', + 'flecks/todos', ], }, ],