chore: Refactored and updated code comments

dev-packages/helpers/src/constants.ts

@@ -1,47 +1,52 @@
 import { DocsConfig } from './models';
 
-export const DECLARATIONS_PATH = `${process.cwd()}/src/options/declarations.ts`;
-
 export const PRESETS_PATH = `${process.cwd()}/src/options/presets.ts`;
 
 export const DOCS_CONFIG: Record<string, DocsConfig> = {
   ['typedoc-plugin-markdown']: {
+    declarationsPath: `${process.cwd()}/src/plugin/options/declarations.ts`,
     optionsPath: 'options',
     docsPath: '',
     declarations: true,
     presets: false,
   },
   ['typedoc-plugin-frontmatter']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'utilities/frontmatter',
     docsPath: '/utilities/frontmatter',
     declarations: true,
     presets: false,
   },
   ['typedoc-plugin-remark']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'utilities/remark',
     docsPath: '/utilities/remark',
     declarations: true,
     presets: false,
   },
   ['typedoc-github-wiki-theme']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'themes/github-wiki',
     docsPath: '/themes/github-wiki',
     declarations: true,
     presets: true,
   },
   ['typedoc-gitlab-wiki-theme']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'themes/gitlab-wiki',
     docsPath: '/themes/gitlab-wiki',
     declarations: true,
     presets: true,
   },
   ['typedoc-vitepress-theme']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'themes/vitepress',
     docsPath: '/themes/vitepress',
     declarations: true,
     presets: false,
   },
   ['docusaurus-plugin-typedoc']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: '/integrations/docusaurus/options',
     docsPath: '/integrations/docusaurus',
     declarations: false,

dev-packages/helpers/src/models.ts

@@ -1,4 +1,5 @@
 export interface DocsConfig {
+  declarationsPath: string;
   optionsPath: string;
   docsPath: string;
   declarations: boolean;

dev-packages/prebuild-options/cli.ts

@@ -10,7 +10,7 @@ main();
 async function main() {
   const docsConfig: DocsConfig = DOCS_CONFIG[getPackageName()];
   if (docsConfig.declarations) {
-    await generateModels();
+    await generateModels(docsConfig.declarationsPath);
   }
   await generateDocs(docsConfig);
   consola.success(`[${getPackageName()}] Prebuild options complete`);

dev-packages/prebuild-options/tasks/generate-docs.ts

@@ -1,4 +1,3 @@
-import { DECLARATIONS_PATH } from '@dev-packages/helpers';
 import { DocsConfig } from '@dev-packages/helpers/src/models';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -21,8 +20,8 @@ export async function generateDocs(docsConfig: DocsConfig) {
 
   // DECLARATIONS
   if (docsConfig.declarations) {
-    const declarationsConfig: any = await import(DECLARATIONS_PATH);
-    const configFileTs = project.getSourceFile(DECLARATIONS_PATH);
+    const declarationsConfig: any = await import(docsConfig.declarationsPath);
+    const configFileTs = project.getSourceFile(docsConfig.declarationsPath);
 
     const optionsVariableStatements =
       configFileTs?.getVariableStatements() as VariableStatement[];

dev-packages/prebuild-options/tasks/generate-models.ts

@@ -1,4 +1,3 @@
-import { DECLARATIONS_PATH } from '@dev-packages/helpers';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as prettier from 'prettier';
@@ -8,8 +7,8 @@ import { DeclarationOption, ParameterType } from 'typedoc';
  * Creates models for plugin options
  */
 
-export async function generateModels() {
-  const optionsConfig = await import(DECLARATIONS_PATH);
+export async function generateModels(declarationsPath: string) {
+  const optionsConfig = await import(declarationsPath);
 
   const mixedTypes = (Object.entries(optionsConfig) as any).filter(
     ([name, option]) =>
@@ -59,9 +58,7 @@ export async function generateModels() {
   `;
 
   const optionsModelFile = path.join(
-    process.cwd(),
-    'src',
-    'options',
+    path.dirname(declarationsPath),
     'models.ts',
   );
 

docs/pages/quick-start.mdx

@@ -31,7 +31,6 @@ The majority of [TypeDoc's options](https://typedoc.org/options/) are supported,
 
 Some typical (and frequently asked about) TypeDoc options that might be useful are:
 
-- Using [githubPages](https://typedoc.org/options/output/#githubpages) to remove the generated `.nojekyll` file.
 - Using [hideGenerator](https://typedoc.org/options/output/#hidegenerator) to prevent outputting links in the footer.
 - Using [disableSources](https://typedoc.org/options/output/#disablesources) to prevent outputting source references.
 - Setting [readme](https://typedoc.org/options/input/#readme) to `none` to exclude the project readme from the docs.

examples/docusaurus3/docusaurus.config.js

@@ -52,6 +52,7 @@ const config = {
         readme: 'none',
         sidebar: { pretty: true },
         outputFileStrategy: 'members',
+        cleanOutputDir: true,
       },
     ],
     [
@@ -61,6 +62,7 @@ const config = {
         out: './docs/api-2',
         ...require(path.join(__dirname, '../../stubs/typedoc.cjs')),
         entryPoints: '../../stubs/src/groups/**/*.ts',
+        cleanOutputDir: true,
       },
     ],
     [
@@ -73,6 +75,7 @@ const config = {
         readme: 'none',
         outputFileStrategy: 'modules',
         entryModule: 'index',
+        cleanOutputDir: true,
       },
     ],
     [

packages/docusaurus-plugin-typedoc/package.json

@@ -23,7 +23,8 @@
     "prepublishOnly": "npm run lint && npm run build",
     "build": "rm -rf ./dist && tsc",
     "build-and-test": "npm run build && npm run test",
-    "test": "jest"
+    "test": "jest",
+    "test:update": "npm test -- -u"
   },
   "author": "Thomas Grey",
   "license": "MIT",

packages/docusaurus-plugin-typedoc/src/options.ts

@@ -7,7 +7,6 @@ const DEFAULT_PLUGIN_OPTIONS = {
   hidePageHeader: true,
   entryFileName: 'index.md',
   theme: 'docusaurus',
-  githubPages: false,
   sidebar: {
     autoConfiguration: true,
     pretty: false,

packages/docusaurus-plugin-typedoc/src/plugin.ts

@@ -56,10 +56,6 @@ async function generateTypedoc(context: any, opts: Partial<PluginOptions>) {
 
   const outputDir = app.options.getValue('out');
 
-  if (options.cleanOutputDir) {
-    removeDir(outputDir);
-  }
-
   if (context.siteConfig?.markdown?.format !== 'mdx') {
     app.renderer.on(PageEvent.END, (event: PageEvent) => {
       event.contents = event.contents?.replace(/\\</g, '<');
@@ -121,30 +117,3 @@ module.exports = typedocSidebar.items;`,
     await app.generateDocs(project, outputDir);
   }
 }
-
-export function writeFileSync(fileName: string, data: string) {
-  fs.mkdirSync(path.dirname(normalizePath(fileName)), { recursive: true });
-  fs.writeFileSync(normalizePath(fileName), data);
-}
-
-export function normalizePath(path: string) {
-  return path.replace(/\\/g, '/');
-}
-
-export function removeDir(path: string) {
-  if (fs.existsSync(path)) {
-    const files = fs.readdirSync(path);
-    if (files.length > 0) {
-      files.forEach(function (filename) {
-        if (fs.statSync(path + '/' + filename).isDirectory()) {
-          removeDir(path + '/' + filename);
-        } else {
-          fs.unlinkSync(path + '/' + filename);
-        }
-      });
-      fs.rmdirSync(path);
-    } else {
-      fs.rmdirSync(path);
-    }
-  }
-}

packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap

@@ -14,10 +14,6 @@ exports[`Docusaurus: Defaults should render 1`] = `
 
 - [module-1](module-1/index.md)
 - [module-2](module-2/index.md)
-
-***
-
-Generated using [TypeDoc](https://typedoc.org) and [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org).
 "
 `;
 
@@ -35,9 +31,5 @@ exports[`Docusaurus: Global members should render 2 1`] = `
 
 - [module-1](module-1/index.md)
 - [module-2](module-2/index.md)
-
-***
-
-Generated using [TypeDoc](https://typedoc.org) and [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org).
 "
 `;

packages/docusaurus-plugin-typedoc/test/specs/docusaurus.spec.ts

@@ -13,6 +13,7 @@ async function bootstrap(
     entryPoints,
     tsconfig: ['./test/stubs/tsconfig.json'],
     readme: 'none',
+    hideGenerator: true,
   };
 
   const plugin = typedocPlugin(

packages/typedoc-github-wiki-theme/src/options/presets.ts

@@ -1,5 +1,4 @@
 export default {
   entryFileName: 'Home.md',
   hidePageHeader: true,
-  githubPages: false,
 };

packages/typedoc-github-wiki-theme/src/theme.ts

@@ -9,21 +9,20 @@ import {
   MarkdownTheme,
   MarkdownThemeRenderContext,
 } from 'typedoc-plugin-markdown';
-import { UrlMapping } from 'typedoc-plugin-markdown/dist/plugin/url-mapping';
 
 export class GithubWikiTheme extends MarkdownTheme {
   override getRenderContext(pageEvent: MarkdownPageEvent<Reflection>) {
     return new ThemeRenderContext(this, pageEvent, this.application.options);
   }
 
-  getUrls(project: ProjectReflection): UrlMapping<any>[] {
+  getUrls(project: ProjectReflection) {
     return super.getUrls(project).map((urlMapping) => {
       if (urlMapping.model.kindOf(ReflectionKind.Project)) {
         return urlMapping;
       }
       return {
         ...urlMapping,
-        url: this.getUrl(urlMapping.model),
+        url: this.getUrl(urlMapping.model as DeclarationReflection),
       };
     });
   }

packages/typedoc-gitlab-wiki-theme/src/options/presets.ts

@@ -1,5 +1,4 @@
 export default {
   entryFileName: 'home.md',
   hidePageHeader: true,
-  githubPages: false,
 };

packages/typedoc-plugin-frontmatter/test/typedoc-base.json

@@ -6,6 +6,5 @@
   "plugin": ["typedoc-plugin-markdown", "typedoc-plugin-frontmatter"],
   "hidePageHeader": true,
   "hideBreadcrumbs": true,
-  "hideGenerator": true,
-  "githubPages": false
+  "hideGenerator": true
 }

packages/typedoc-plugin-markdown/CONTRIBUTING.md

@@ -1,3 +1,82 @@
 # Contributing guidelines
 
-Contributions and suggestions are welcome. Contributing guidelines coming soon.
+> Please note this guide is work in progress!
+
+Thank you showing interest in contributing to this plugin - contributions and suggestions are very welcome.
+
+## Overview
+
+This is a simple monorepo managed by [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces) with `typedoc-plugin-markdown` the "core" package. This guide is for developing inside the `typedoc-plugin-markdown` core package.
+
+This guide does not cover TypeDoc specifically so it might be useful to read the [TypeDoc development guide](https://typedoc.org/guides/development/) for an overview on TypeDoc's architecture.
+
+## Getting started
+
+1. Clone the repository:<br />`git clone git@github.com:tgreyuk/typedoc-plugin-markdown.git`
+
+2. Checkout the `next` branch:<br />`git checkout next`
+
+3. Install dependecnices from the repository root.<br />`npm install`
+
+4. cd into the package:<br />`cd packages/typedoc-plugin-markdown`
+
+5. Build and run tests:<br />`npm run build-and-test`
+
+If the project builds and the tests run successfully you are ready to get going.
+
+## High-level architecture
+
+At a high level the codebase consists of an exposed TypeDoc plugin along side an assoicated theme.
+
+At a highlevel:
+
+- `index.ts` contains the public api and exports the required `load` funtion.
+- The `plugin` folder contains functionality to setup the plugin and configure the renderer.
+- The `support` folder contains agnostic support helpers used in the plugin.
+- The `theme` folder contains the logic that sets up the custom Markdown theme.
+
+## Testing
+
+Test use the [Jest](https://jestjs.io/) with [ts-jest](https://kulshekhar.github.io/ts-jest/) as the test framework. To run all tests use the following command:
+
+```shell
+npm run test
+```
+
+Jest snapshots are used quite heavily to compare the output generated from templates. To update the snapshots run with the `update` flag.
+
+## Linting
+
+To run linting on the project use:
+
+```shell
+npm run lint
+```
+
+Both the code and some example generated markdown are linted using [eslint](https://eslint.org/) and [markdowmlint](https://github.com/DavidAnson/markdownlint) respectively.
+
+## Submitting a PR
+
+Please create a PR with a clear description of what the change is.
+
+If the PR requires a new package release please also create a [changeset](https://github.com/changesets/changesets) which is the tool used for versioning and releasing packages.
+
+Run the changeset command in the project root:
+
+```shell
+npx changeset
+```
+
+A one line changeset description will be enough but please ensure the correct semantic version is selected `patch` for a bug fix or `minor` for a new feature.
+
+The resulting changeset file will something like this:
+
+```markdown
+---
+'typedoc-plugin-markdown': patch
+---
+
+- A simple description for a patch fix. This message will also appear in the changelog.
+```
+
+Please also submit this file with the PR.

packages/typedoc-plugin-markdown/package.json

@@ -11,13 +11,14 @@
     "prepublishOnly": "npm run lint && npm run build",
     "prebuild": "rm -rf dist && prebuild-options && ts-node scripts/prebuild-resources",
     "build": "tsc",
-    "pretest": "ts-node ./test/__scripts__/prepare.ts",
-    "test": "npm-run-all test:*",
-    "test:lint-md": "node test/__scripts__/lint.md.mjs",
-    "test:lint-mdx": "node test/__scripts__/lint.mdx.mjs",
-    "test:jest": "jest",
+    "pretest": "ts-node ./test/__scripts__/prepare",
+    "test-md": "node test/__scripts__/lint.md.mjs",
+    "test-mdx": "node test/__scripts__/lint.mdx.mjs",
+    "test": "npm run test-md && npm run test-mdx && jest",
+    "test:update": "npm run build && npm test -- -u",
     "build-and-run": "npm run build && npm run pretest",
-    "build-and-test": "npm run build && npm run test"
+    "build-and-test": "npm run build && npm run test",
+    "docs": "npm run build && typedoc --out ./docs/api"
   },
   "author": "Thomas Grey",
   "license": "MIT",