From eb21cb439e746127ec0ffa128f67f0ee2e6b4767 Mon Sep 17 00:00:00 2001 From: tgreyuk Date: Sat, 18 Sep 2021 11:18:58 +0100 Subject: [PATCH] fix: remove manual sidebar generation and fix pre-render docs order (#251) --- packages/docusaurus-plugin-typedoc/README.md | 104 ++++++++++-------- .../docusaurus-plugin-typedoc/package.json | 4 +- .../docusaurus-plugin-typedoc/src/options.ts | 1 - .../docusaurus-plugin-typedoc/src/plugin.ts | 6 - .../docusaurus-plugin-typedoc/src/render.ts | 28 +++++ .../docusaurus-plugin-typedoc/src/sidebar.ts | 18 --- .../docusaurus-plugin-typedoc/src/types.ts | 1 - .../specs/__snapshots__/options.spec.ts.snap | 2 - .../test/specs/options.spec.ts | 1 - 9 files changed, 89 insertions(+), 76 deletions(-) delete mode 100644 packages/docusaurus-plugin-typedoc/src/sidebar.ts diff --git a/packages/docusaurus-plugin-typedoc/README.md b/packages/docusaurus-plugin-typedoc/README.md index 7056b2f63..580c8a749 100644 --- a/packages/docusaurus-plugin-typedoc/README.md +++ b/packages/docusaurus-plugin-typedoc/README.md @@ -61,49 +61,6 @@ website/ (docusaururs website root) ├── sidebars.js ``` -### Sidebar - -`sidebars.js` can be configured in following ways: - -1 ) Generate the entire sidebar from file structure of your docs folder (default behaviour): - -```js -module.exports = { - someSidebar: [ - { - type: 'autogenerated', - dirName: '.', // '.' means the docs folder - }, - ], -}; -``` - -2 ) Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar. -(note:`sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation) - - -```js -module.exports = { - someSidebar: { - 'Category 1': ['doc1', 'doc2', 'doc3'], - - // use seperate generated file - 'API': require('./typedoc-sidebar.js'), - - // or write inline - 'API': [ - { - type: 'autogenerated', - dirName: 'api', // 'api' is the 'out' directory - }, - ], - }, -}; -``` - -> To maintain backward compatibility with previous versions a `./typedoc-sidebar.js` is created by default. Pass `sidebar.sidebarFile:null` to prevent this. - -Please see https://docusaurus.io/docs/sidebar for sidebar documentation. ## Options @@ -142,8 +99,6 @@ Note: Options declared in this manner will take priority and overwrite options d | `sidebar.fullNames` | `false` | Display full names with module path. | | `sidebar.position` | `null` | The position of the sidebar in the tree. | -If the manual sidebar is not required pass `sidebar.sidebarFile: null` to skip sidebar generation. - ### An example configuration ```js @@ -171,6 +126,65 @@ module.exports = { }; ``` +### Sidebar and Navbar + +#### Sidebar + +`sidebars.js` can be configured in following ways: + +1 ) Generate the entire sidebar from file structure of your docs folder (default behaviour): + +```js +module.exports = { + sidebar: [ + { + type: 'autogenerated', + dirName: '.', // '.' means the docs folder + }, + ], +}; +``` + +2 ) Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar. + +>note: `sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation) + +```js +module.exports = { + sidebar: { + 'Category 1': ['doc1', 'doc2', 'doc3'], + 'API': [ + { + type: 'autogenerated', + dirName: 'api', // 'api' is the 'out' directory + }, + ], + }, +}; +``` + +Please see https://docusaurus.io/docs/sidebar for sidebar documentation. + +#### Navbar + +A navbar item can be configured in `themeConfig` options in `docusaurus.config.js`: + +```js + themeConfig: { + navbar: { + items: [ + { + to: 'docs/api/', // 'api' is the 'out' directory + activeBasePath: 'docs', + label: 'API', + position: 'left', + }, + ], + }, +}, +``` + +Please see https://docusaurus.io/docs/api/themes/configuration#navbar-items for navbar documentation. ## Additional config diff --git a/packages/docusaurus-plugin-typedoc/package.json b/packages/docusaurus-plugin-typedoc/package.json index 994f154d1..9233dbab0 100644 --- a/packages/docusaurus-plugin-typedoc/package.json +++ b/packages/docusaurus-plugin-typedoc/package.json @@ -28,8 +28,8 @@ "build": "rm -rf ./dist && tsc", "build-and-test": "yarn run build && yarn run test", "test:init": "rm -rf test/site && npx @docusaurus/init@latest init test/site classic", - "test:demo:start": "yarn run build && cd test/site && yarn run clear && yarn run start", - "test:demo:build": "yarn run build && cd test/site && yarn run clear && yarn run build && yarn run serve", + "test:demo:start": "rm -rf test/site/docs/api yarn run build && cd test/site && yarn run clear && yarn run start", + "test:demo:build": "rm -rf test/site/docs/api && yarn run build && cd test/site && yarn run clear && yarn run build && yarn run serve", "test": "jest --colors" }, "author": "Thomas Grey", diff --git a/packages/docusaurus-plugin-typedoc/src/options.ts b/packages/docusaurus-plugin-typedoc/src/options.ts index d54cdbbd0..a06cfeba2 100644 --- a/packages/docusaurus-plugin-typedoc/src/options.ts +++ b/packages/docusaurus-plugin-typedoc/src/options.ts @@ -8,7 +8,6 @@ const DEFAULT_PLUGIN_OPTIONS: PluginOptions = { out: 'api', sidebar: { fullNames: false, - sidebarFile: 'typedoc-sidebar.js', categoryLabel: 'API', indexLabel: undefined, readmeLabel: 'Readme', diff --git a/packages/docusaurus-plugin-typedoc/src/plugin.ts b/packages/docusaurus-plugin-typedoc/src/plugin.ts index 70ad83519..df2603adf 100644 --- a/packages/docusaurus-plugin-typedoc/src/plugin.ts +++ b/packages/docusaurus-plugin-typedoc/src/plugin.ts @@ -6,7 +6,6 @@ import { load } from 'typedoc-plugin-markdown'; import { getOutputDirectory } from './options'; import { bootstrap } from './render'; -import { writeSidebar } from './sidebar'; import { PluginOptions } from './types'; // store list of plugin ids when running multiple instances @@ -29,11 +28,6 @@ export default async function pluginDocusaurus( const options = bootstrap(app, opts); - // Do not break legacy manual sidebar generation implementations - if (options.sidebar.sidebarFile) { - writeSidebar(siteDir, options); - } - const project = app.convert(); // if project is undefined typedoc has a problem - error logging will be supplied by typedoc. diff --git a/packages/docusaurus-plugin-typedoc/src/render.ts b/packages/docusaurus-plugin-typedoc/src/render.ts index 6a3d2f9a8..cd47b4312 100644 --- a/packages/docusaurus-plugin-typedoc/src/render.ts +++ b/packages/docusaurus-plugin-typedoc/src/render.ts @@ -2,9 +2,12 @@ import { Application, MixedDeclarationOption, ParameterType, + ProjectReflection, + RendererEvent, StringDeclarationOption, TSConfigReader, TypeDocReader, + UrlMapping, } from 'typedoc'; import { getPluginOptions } from './options'; @@ -14,10 +17,35 @@ import { PluginOptions } from './types'; export const bootstrap = (app: Application, opts: Partial) => { addTypedocReaders(app); addTypedocDeclarations(app); + app.renderer.render = render; app.bootstrap({ ...getPluginOptions(opts) }); return app.options.getRawValues() as PluginOptions; }; +async function render(project: ProjectReflection, outputDirectory: string) { + if ( + !this.prepareTheme() || + !(await this.prepareOutputDirectory(outputDirectory)) + ) { + return; + } + const output = new RendererEvent( + RendererEvent.BEGIN, + outputDirectory, + project, + ); + output.urls = this.theme!.getUrls(project); + this.trigger(output); + if (!output.isDefaultPrevented) { + output?.urls?.forEach((mapping: UrlMapping) => { + this.renderDocument(output.createPageEvent(mapping)); + }); + + this.trigger(RendererEvent.END, output); + } + this.theme = void 0; +} + const addTypedocReaders = (app: Application) => { app.options.addReader(new TypeDocReader()); app.options.addReader(new TSConfigReader()); diff --git a/packages/docusaurus-plugin-typedoc/src/sidebar.ts b/packages/docusaurus-plugin-typedoc/src/sidebar.ts deleted file mode 100644 index 61bb9d533..000000000 --- a/packages/docusaurus-plugin-typedoc/src/sidebar.ts +++ /dev/null @@ -1,18 +0,0 @@ -import * as fs from 'fs'; -import * as path from 'path'; - -import { PluginOptions } from './types'; - -export const writeSidebar = (siteDir: string, options: PluginOptions) => { - const sidebarPath = path.resolve(siteDir, options.sidebar.sidebarFile); - if (!fs.existsSync(path.dirname(sidebarPath))) { - fs.mkdirSync(path.dirname(sidebarPath)); - } - fs.writeFileSync( - sidebarPath, - `module.exports=[{type:'autogenerated',dirName:'${path.relative( - process.cwd(), - options.out, - )}'}];`, - ); -}; diff --git a/packages/docusaurus-plugin-typedoc/src/types.ts b/packages/docusaurus-plugin-typedoc/src/types.ts index 25875fb35..76bb37e09 100644 --- a/packages/docusaurus-plugin-typedoc/src/types.ts +++ b/packages/docusaurus-plugin-typedoc/src/types.ts @@ -28,7 +28,6 @@ export interface FrontMatter { export interface SidebarOptions { fullNames?: boolean; - sidebarFile: string; //deprecated categoryLabel: string; indexLabel?: string; readmeLabel?: string; diff --git a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/options.spec.ts.snap b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/options.spec.ts.snap index 276cfe765..7f1014f39 100644 --- a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/options.spec.ts.snap +++ b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/options.spec.ts.snap @@ -7,7 +7,6 @@ Object { "indexLabel": "Custom index", "position": null, "readmeLabel": "Custom readme", - "sidebarFile": "custom-sidebar.js", } `; @@ -38,7 +37,6 @@ Object { "indexLabel": undefined, "position": null, "readmeLabel": "Readme", - "sidebarFile": "typedoc-sidebar.js", }, "watch": false, } diff --git a/packages/docusaurus-plugin-typedoc/test/specs/options.spec.ts b/packages/docusaurus-plugin-typedoc/test/specs/options.spec.ts index 84ae046c5..1edb13387 100644 --- a/packages/docusaurus-plugin-typedoc/test/specs/options.spec.ts +++ b/packages/docusaurus-plugin-typedoc/test/specs/options.spec.ts @@ -19,7 +19,6 @@ describe(`Options:`, () => { expect( getPluginOptions({ sidebar: { - sidebarFile: 'custom-sidebar.js', fullNames: true, indexLabel: 'Custom index', readmeLabel: 'Custom readme',