docs(typedoc): Initial TypeDoc setup (#43)

* docs(typedoc): Typedoc setup

* update typedoc version

* change typedoc output directory to docs/

* remove generated docs

Co-authored-by: Christian <[email protected]>

Author: ChristianSama

.gitignore

@@ -1,4 +1,5 @@
 # Build
+docs/build/
 build/
 dist/
 

README.md

@@ -61,6 +61,9 @@ For a list of all matchers and extended documentation, please refer to the API d
 - [Jest Integration](docs/jest-tutorial.md)
 - [Mocha Integration](docs/mocha-tutorial.md)
 
+## API Reference
+You can find the full API reference [here](/docs/pages/index.html)
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

package.json

@@ -15,6 +15,7 @@
     "check": "yarn compile && yarn lint && yarn test --forbid-only",
     "compile": "tsc -p tsconfig.json",
     "lint": "tslint -c tslint.json \"!(build|dist)/**/*.ts\"",
+    "pages": "typedoc",
     "test": "cross-env NODE_ENV=test TS_NODE_TRANSPILE_ONLY=true mocha"
   },
   "dependencies": {
@@ -30,6 +31,9 @@
     "sinon": "^14.0.0",
     "ts-node": "^10.9.1",
     "tslint": "^6.1.3",
+    "typedoc": "^0.23.9",
+    "typedoc-plugin-merge-modules": "^4.0.1",
+    "typedoc-theme-hierarchy": "^3.0.0",
     "typescript": "^4.7.4"
   },
   "packageManager": "[email protected]"

src/lib/Assertion.ts

@@ -5,7 +5,7 @@ import { UnsupportedOperationError } from "./errors/UnsupportedOperationError";
 import { isJSObject, isKeyOf } from "./helpers/guards";
 import { TypeFactory } from "./helpers/TypeFactories";
 
-interface ExecuteOptions {
+export interface ExecuteOptions {
   /**
    * The condition for when the assertion should pass. The negation of this
    * condition is also used for the `.not` case of the assertion
@@ -311,7 +311,7 @@ export class Assertion<T> {
    * an assertion instance for that specific type. The new assertion is built
    * from a factory that should extend from the base {@link Assertion} class.
    *
-   * We provide some basic factories in {@code TypeFactories}. If you need some
+   * We provide some basic factories in `TypeFactories`. If you need some
    * other factory for a custom assertion for instance, you can easily create
    * one from a Factory reference and a predicate.
    *

src/lib/FunctionAssertion.ts

@@ -6,7 +6,7 @@ import { TypeFactory } from "./helpers/TypeFactories";
 
 export type AnyFunction = (...args: any[]) => any;
 
-interface Class<T> extends Function {
+export interface Class<T> extends Function {
   prototype: T;
 }
 
@@ -51,7 +51,7 @@ export class FunctionAssertion<T extends AnyFunction> extends Assertion<T> {
   }
 
   /**
-   * Check if the function throws an {@link Error}. If the `ErrorType` is passed,
+   * Check if the function throws an `Error`. If the `ErrorType` is passed,
    * it also checks if the error is an instance of the specific type.
    *
    * @example
@@ -66,7 +66,7 @@ export class FunctionAssertion<T extends AnyFunction> extends Assertion<T> {
    * ```
    *
    * @param ErrorType optional error type constructor to check the thrown error
-   *                  against. If is not provided, it defaults to {@link Error}
+   *                  against. If is not provided, it defaults to `Error`
    * @returns a new {@link ErrorAssertion} to assert over the error
    */
   public toThrowError(): ErrorAssertion<Error>;

src/lib/NumberAssertion.ts

@@ -3,11 +3,11 @@ import { AssertionError } from "assert";
 import { Assertion } from "./Assertion";
 import { isHighInclusiveOptions, isInclusiveOptions, isLowInclusiveOptions } from "./helpers/guards";
 
-interface BaseBetweenOptions {
+export interface BaseBetweenOptions {
   range: [number, number];
 }
 
-interface CloseToOptions {
+export interface CloseToOptions {
   value: number;
   withOffset: number;
 }
@@ -105,7 +105,7 @@ export class NumberAssertion extends Assertion<number> {
 
   /**
    * Check if the number is finite. That is, when the number is not a
-   * JavaScript's {@link Infinity} value. Keep in mind that this includes
+   * JavaScript's `Infinity` value. Keep in mind that this includes
    * positive and negative infinity.
    *
    * @returns the assertion instance
@@ -129,7 +129,7 @@ export class NumberAssertion extends Assertion<number> {
 
   /**
    * Check if the number is `NaN`. That is only when the number is JavaScript's
-   * {@link NaN} value.
+   * `NaN` value.
    *
    * @returns the assertion instance
    */
@@ -200,7 +200,7 @@ export class NumberAssertion extends Assertion<number> {
    * bounds are exclusive, but the options allow to set the high, low, or both
    * limits as inclusive
    *
-   * @param options an object of type {@link Between Options} where the `range`
+   * @param options an object of type {@link BetweenOptions} where the `range`
    *                property defines the bounds, so it's always required. Use
    *                `inclusive: true` to make both limits inclusive. Or you can
    *                selectively make low or high limits inclusive using

src/lib/ObjectAssertion.ts

@@ -5,7 +5,7 @@ import { Assertion } from "./Assertion";
 
 export type JSObject = Record<keyof any, unknown>;
 
-type Entry<T, K = keyof T> = K extends keyof T
+export type Entry<T, K = keyof T> = K extends keyof T
   ? [K, T[K]]
   : never;
 

src/lib/expect.ts

@@ -10,9 +10,9 @@ import { JSObject, ObjectAssertion } from "./ObjectAssertion";
 import { PromiseAssertion } from "./PromiseAssertion";
 import { StringAssertion } from "./StringAssertion";
 
-type PromiseType<T> = T extends Promise<infer X> ? X : never;
+export type PromiseType<T> = T extends Promise<infer X> ? X : never;
 
-type ArrayType<T> = T extends Array<infer X> ? X : never;
+export type ArrayType<T> = T extends Array<infer X> ? X : never;
 
 export function expect<T extends boolean>(actual: T): BooleanAssertion;
 export function expect<T extends number>(actual: T): NumberAssertion;

src/lib/helpers/TypeFactories.ts

@@ -9,15 +9,15 @@ import { StringAssertion } from "../StringAssertion";
 
 import { isJSObject } from "./guards";
 
-type AssertionFactory<S, A extends Assertion<S>> = new(actual: S) => A;
+export type AssertionFactory<S, A extends Assertion<S>> = new(actual: S) => A;
 
 export interface TypeFactory<S, A extends Assertion<S>> {
   Factory: AssertionFactory<S, A>;
   predicate(value: unknown): value is S;
   typeName: string;
 }
 
-interface StaticTypeFactories {
+export interface StaticTypeFactories {
   Boolean: TypeFactory<boolean, BooleanAssertion>;
   Date: TypeFactory<Date, DateAssertion>;
   Function: TypeFactory<AnyFunction, FunctionAssertion<AnyFunction>>;

typedoc.json

@@ -0,0 +1,25 @@
+{
+  "cleanOutputDir": false,
+  "entryPoints": ["src/lib"],
+  "entryPointStrategy": "expand",
+  "githubPages": true,
+  "includeVersion": true,
+  "mergeModulesMergeMode": "project",
+  "mergeModulesRenameDefaults": true,
+  "name": "assertive-ts",
+  "out": "docs/build",
+  "plugin": [
+    "typedoc-theme-hierarchy",
+    "typedoc-plugin-merge-modules"
+  ],
+  "readme": "none",
+  "theme": "hierarchy",
+  "visibilityFilters": {
+    "@alpha": false,
+    "@beta": false,
+    "external": false,
+    "inherited": true,
+    "private": false,
+    "protected": false
+  }
+}