Merge pull request #1726 from srmagura/example

The TypeDoc example

Author: Gerrit0

.config/.prettierignore

@@ -1,8 +1,10 @@
 ../.nyc_output
 ../coverage
 ../dist
-../package-lock.json
+**/package-lock.json
 ../src/test/**/specs*.json
 ../src/test/packages/**/*.js
 ../src/test/renderer/specs
+../src/test/renderer/testProject
 ../static/main.js
+../example/docs/

.eslintrc

@@ -16,13 +16,13 @@
     ],
     "ignorePatterns": [
         "src/test/renderer/specs",
-        "examples",
         "dist",
         "coverage",
         "static/main.js",
         "src/lib/output/themes/default/assets",
         // Would be nice to lint these, but they shouldn't be included in the project,
         // so we need a second eslint config file.
+        "example",
         "src/test/converter",
         "src/test/converter2",
         "src/test/module",

.gitignore

@@ -9,7 +9,7 @@ yarn-error.log
 
 /src/test/renderer/*/doc
 /src/test/renderer/testProject/json.json
-/node_modules/
+**/node_modules/
 /coverage/
 /dist/
 
@@ -21,3 +21,5 @@ src/test/renderer/specs/specs.json
 
 # Built theme JS
 static/main.js
+
+/example/docs/

.vscode/settings.json

@@ -8,5 +8,6 @@
     },
     "prettier.enable": true,
     "prettier.configPath": ".config/.prettierrc.json",
-    "prettier.ignorePath": ".config/.prettierignore"
+    "prettier.ignorePath": ".config/.prettierignore",
+    "eslint.workingDirectories": [".", "./example"]
 }

example/.eslintrc.json

@@ -0,0 +1,7 @@
+{
+    "extends": "../.eslintrc",
+    "parserOptions": {
+        "project": "./tsconfig.json"
+    },
+    "ignorePatterns": ["docs/"]
+}

example/README.md

@@ -0,0 +1,72 @@
+# The TypeDoc Example
+
+Welcome to the TypeDoc example! TypeDoc is a documentation generator for
+TypeScript.
+
+TypeDoc automatically documents every variable, function, and class
+that is exported by your project. You can add explanations and examples to your
+documentation site by annotating your code with doc comments, e.g.
+
+```
+/**
+ * Calculates the square root of a number.
+ *
+ * @param x the number to calculate the root of.
+ * @returns the square root if `x` is non-negative or `NaN` if `x` is negative.
+ */
+export function sqrt(x: number): number {
+    return Math.sqrt(x);
+}
+```
+
+This project shows off some of TypeDoc's features:
+
+-   Built-in support for various TypeScript language constructs
+-   Markdown in doc comments
+-   Syntax highligting in code blocks
+
+## Index of Examples
+
+**Click the "Exports" link in the sidebar to see a complete list of everything in
+the package.**
+
+Here are some examples we wanted to highlight:
+
+### Rendering
+
+-   Markdown showcase: [[`markdownShowcase`]]
+-   Syntax highlighting showcase: [[`syntaxHighlightingShowcase`]]
+
+### Functions
+
+-   Simple functions: [[`sqrt`]] and [[`sqrtArrowFunction`]]
+-   A generic function: [[`concat`]]
+-   Functions that take an options object: [[`makeHttpCallA`]] and [[`makeHttpCallB`]]
+-   An overloaded function: [[`overloadedFunction`]]
+-   An external function exported under a different name: [[`lodashSortBy`]]
+
+### Types
+
+-   Type aliases: [[`SimpleTypeAlias`]] and [[`ComplexGenericTypeAlias`]]
+-   Interfaces: [[`User`]] and [[`AdminUser`]]
+
+### Classes
+
+-   A basic class: [[`Customer`]]
+-   A subclass: [[`DeliveryCustomer`]]
+-   A complex class: [[`CancellablePromise`]]
+-   A class that extends a built-in generic type: [[`StringArray`]]
+
+### Enums
+
+-   A basic enum: [[`SimpleEnum`]]
+-   Using the `@enum` tag: [[`EnumLikeObject`]]
+
+### Variables
+
+-   [[`PI`]], [[`STRING_CONSTANT`]], and [[`ObjectConstant`]]
+
+### React Components
+
+-   Basic React components: [[`CardA`]] and [[`CardB`]]
+-   A complex React component: [[`EasyFormDialog`]] and [[`EasyFormDialogProps`]]

example/building-the-example.md

@@ -0,0 +1,7 @@
+# Building the TypeDoc Example
+
+1. Build TypeDoc: `npm install` and `npm run build` in the root directory.
+2. `cd example`
+3. `npm install` (the example has its own `package.json`)
+4. Typecheck the example: `npm run tsc`
+5. Build the docs: `npm run typedoc`