Merge pull request #103 from microsoft/tsconfig_doc

TSConfig Reference Overview

.github/workflows/CI.yml

@@ -0,0 +1,30 @@
+name: Build Website
+
+on:
+  pull_request
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    # Check out, and set up the node/ruby infra
+    - uses: actions/checkout@v1
+    - uses: actions/setup-node@v1
+
+    # Get local dependencies
+    - run: yarn install
+    - run: yarn bootstrap
+    - run: yarn build
+
+    # PR: Deploy if we can
+    - name: Deploy PR Version
+      if: github.event_name == 'pull_request'
+      run: 'if test -z "$NOW_ACCESS_TOKEN"; then echo "Skipping deploy";
+            else npx now packages/typescriptlang-org/public/ --token="$NOW_ACCESS_TOKEN"  --name="typescript-v2-$PR_NUMBER"; fi'
+      env:
+        NOW_ACCESS_TOKEN: ${{ secrets.NOW_ACCESS_TOKEN }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+
+    # Run any tests
+    - run: yarn workspaces run test --ci

.gitignore

@@ -66,5 +66,3 @@ typings/
 # tdsx
 dist
 
-packages/typescriptlang-org/schema.json
-packages/typescriptlang-org/apollo.config.js

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "semi": false,
+  "printWidth": 120
+}

.vscode/settings.json

@@ -1,5 +1,13 @@
 {
   "files.exclude": {
     "**/.rts2_cache*": true
-  }
-}
+  },
+  "workbench.colorCustomizations": {
+    "activityBar.background": "#3178C6",
+    "activityBar.foreground": "#000000",
+    "activityBar.inactiveForeground": "#15202b99",
+    "activityBarBadge.background": "#ffffff",
+    "activityBarBadge.foreground": "#15202b"
+  },
+  "peacock.color": "#3178C6",
+}

README.md

@@ -6,6 +6,7 @@ This repo uses [yarn workspaces][y-wrk], to get started clone this repo and run
 git clone https://github.com/microsoft/TypeScript-website
 cd TypeScript-website
 yarn install
+yarn bootstrap
 code .
 ```
 
@@ -32,6 +33,10 @@ Then opening: http://localhost:1234 - which is the below package.
 
 A create-react-app for working on the playground.
 
+## TSConfig Reference
+
+A set of tools and scripts for generating a comprehensive API reference for the TSConfig JSON file.
+
 # Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

package.json

@@ -9,8 +9,11 @@
     "husky": "^3.0.8"
   },
   "scripts": {
+    "bootstrap": "yarn build-tsconfig-reference-md",
     "start": "yarn workspace typescriptlang-org start",
-    "build": "yarn workspace typescriptlang-org build",
+    "build-site": "yarn workspace typescriptlang-org build",
+    "build-tsconfig-reference-md": "yarn workspace tsconfig-reference build",
+    "build": "yarn build-tsconfig-reference-md && yarn build-site",
     "clean": "yarn workspace typescriptlang-org gatsby clean",
     "test": "yarn jest",
     "playground": "concurrently -p \"[{name}]\" -n \"TS,WEB\" -c \"bgBlue.bold,bgMagenta.bold\" \"yarn workspace playground start\" \"yarn workspace playground-sandbox start\"",
@@ -24,7 +27,7 @@
   },
   "husky": {
     "hooks": {
-      "pre-push": "git-branch-is v2 &&  yarn run clean && yarn run build"
+      "pre-push": "git-branch-is v2 && yarn run clean && yarn run build || echo 'skipping'"
     }
   }
 }

packages/examples/en/TypeScript/Language/Soundness.ts

@@ -1,3 +1,5 @@
+//// { order: 1, compiler: { strictFunctionTypes: false } }
+
 // Without a background in type theory, you're unlikely
 // to be familiar with the idea of a type system being "sound".
 

packages/playground/package.json

@@ -5,15 +5,16 @@
   "license": "MIT",
   "scripts": {
     "start": "parcel index.html",
-    "build": "parcel build index.html"
+    "build": "parcel build index.html",
+    "test": "echo 'no tests'"
   },
   "dependencies": {
     "react-app-polyfill": "^1.0.0"
   },
   "devDependencies": {
     "@types/react": "^16.8.15",
     "@types/react-dom": "^16.8.4",
-    "parcel": "^1.12.3",
+    "parcel": "^1.12.4",
     "typescript": "^3.4.5"
   }
 }

packages/sandbox/package.json

@@ -10,7 +10,7 @@
   "scripts": {
     "start": "tsdx watch",
     "build": "tsdx build",
-    "test": "tsdx test --env=jsdom",
+    "test": "echo 'no tests'; #tsdx test --env=jsdom",
     "lint": "tsdx lint"
   },
   "peerDependencies": {
@@ -22,16 +22,16 @@
     }
   },
   "devDependencies": {
-    "@types/jest": "^24.0.17",
-    "@types/react": "^16.9.2",
-    "@types/react-dom": "^16.8.5",
-    "husky": "^3.0.4",
+    "@types/jest": "^24.0.18",
+    "@types/react": "^16.9.5",
+    "@types/react-dom": "^16.9.1",
+    "husky": "^3.0.8",
     "prettier": "^1.18.2",
     "pretty-quick": "^1.11.1",
-    "react": "^16.9.0",
-    "react-dom": "^16.9.0",
-    "tsdx": "^0.8.0",
+    "react": "^16.10.2",
+    "react-dom": "^16.10.2",
+    "tsdx": "^0.9.3",
     "tslib": "^1.10.0",
-    "typescript": "^3.5.3"
+    "typescript": "^3.6.3"
   }
 }

packages/tsconfig-reference/README.md

@@ -0,0 +1,31 @@
+### Generating the TSConfig Reference
+
+This "package" hosts multi-lingual docs for the TSConfig. As much as possible is based
+off pulling data from `require("typescript")` then augmented with markdown from inside the
+[`./copy`](./copy) folder.
+
+## Contributing
+
+To improve a single compiler option's documentation; all you need to do is go into the [`./copy`](./copy) folder and
+edit the page option in markdown and send a PR. No need to leave GitHub. 
+
+Then, during a deploy, all of the markdown files are bundled together and any merged changes are uploaded.
+
+## Contributing a new language
+
+If you'd like to create a new language:
+
+- Do you plan on making an evening or two on it and go all out? then you can use the 
+  script [`./scripts/createLanguage.ts`](./scripts/createLanguage.ts) to set up a new language. 
+
+- Do you want to work on it incrementally? Create a new subfolder in `./copy` with your language code and
+  then make sure the files you work on have the same name as English and your changes will overwrite the English 
+  version.
+
+## Building
+
+The TSConfig reference is created by a two step process:
+
+- Creating the JSON dump of all the useful info via [`./scripts/generateJSON.ts`](scripts/generateJSON.ts) which you can find in [`./data`](./data).
+
+- A script which uses the JSON, and the copy to generate per-language markdown docs which are meant to be embedded inside webpages ``

packages/tsconfig-reference/copy/en/categories/Additional_Checks_6176.md

@@ -0,0 +1,5 @@
+---
+display: "Additional Checks"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Advanced_Options_6178.md

@@ -0,0 +1,5 @@
+---
+display: "Advanced"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Basic_Options_6172.md

@@ -0,0 +1,5 @@
+---
+display: "Basic Options"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Command_line_Options_6171.md

@@ -0,0 +1,5 @@
+---
+display: "Command Line"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Experimental_Options_6177.md

@@ -0,0 +1,5 @@
+---
+display: "Experimental"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Module_Resolution_Options_6174.md

@@ -0,0 +1,5 @@
+---
+display: "Module Resolution"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Source_Map_Options_6175.md

@@ -0,0 +1,5 @@
+---
+display: "Source Maps"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/categories/Strict_Type_Checking_Options_6173.md

@@ -0,0 +1,5 @@
+---
+display: "Strict Checks"
+---
+
+Additional Checks Copy

packages/tsconfig-reference/copy/en/options/allowJs.md

@@ -0,0 +1,5 @@
+---
+display: "Allow JS"
+---
+
+Allow javascript files to be compiled.

packages/tsconfig-reference/copy/en/options/allowSyntheticDefaultImports.md

@@ -0,0 +1,5 @@
+---
+display: "Allow Synthetic Default Imports"
+---
+
+Allow default imports from modules with no default export. This does not affect code emit, just typechecking.

packages/tsconfig-reference/copy/en/options/allowUmdGlobalAccess.md

@@ -0,0 +1,5 @@
+---
+display: "Allow Umd Global Access"
+---
+
+Allow accessing UMD globals from modules.

packages/tsconfig-reference/copy/en/options/allowUnreachableCode.md

@@ -0,0 +1,5 @@
+---
+display: "Allow Unreachable Code"
+---
+
+Do not report errors on unreachable code.

packages/tsconfig-reference/copy/en/options/allowUnusedLabels.md

@@ -0,0 +1,5 @@
+---
+display: "Allow Unused Labels"
+---
+
+Do not report errors on unused labels.

packages/tsconfig-reference/copy/en/options/alwaysStrict.md

@@ -0,0 +1,5 @@
+---
+display: "Always Strict"
+---
+
+Parse in strict mode and emit "use strict" for each source file.

packages/tsconfig-reference/copy/en/options/baseUrl.md

@@ -0,0 +1,5 @@
+---
+display: "Base Url"
+---
+
+Base directory to resolve non-absolute module names.

packages/tsconfig-reference/copy/en/options/charset.md

@@ -0,0 +1,5 @@
+---
+display: "Charset"
+---
+
+The character set of the input files.

packages/tsconfig-reference/copy/en/options/checkJs.md

@@ -0,0 +1,5 @@
+---
+display: "Check JS"
+---
+
+Report errors in .js files.

packages/tsconfig-reference/copy/en/options/composite.md

@@ -0,0 +1,5 @@
+---
+display: "Composite"
+---
+
+Enable project compilation

packages/tsconfig-reference/copy/en/options/declaration.md

@@ -0,0 +1,5 @@
+---
+display: "Declaration"
+---
+
+Generates corresponding '.d.ts' file.

packages/tsconfig-reference/copy/en/options/declarationDir.md

@@ -0,0 +1,5 @@
+---
+display: "Declaration Dir"
+---
+
+Output directory for generated declaration files.

packages/tsconfig-reference/copy/en/options/declarationMap.md

@@ -0,0 +1,5 @@
+---
+display: "Declaration Map"
+---
+
+Generates a sourcemap for each corresponding '.d.ts' file.

packages/tsconfig-reference/copy/en/options/diagnostics.md

@@ -0,0 +1,5 @@
+---
+display: "Diagnostics"
+---
+
+Show diagnostic information.

packages/tsconfig-reference/copy/en/options/disableSizeLimit.md

@@ -0,0 +1,5 @@
+---
+display: "Disable Size Limit"
+---
+
+Disable size limitations on JavaScript projects.

packages/tsconfig-reference/copy/en/options/downlevelIteration.md

@@ -0,0 +1,5 @@
+---
+display: "Downlevel Iteration"
+---
+
+Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'.

packages/tsconfig-reference/copy/en/options/emitBOM.md

@@ -0,0 +1,5 @@
+---
+display: "Emit B O M"
+---
+
+Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.

packages/tsconfig-reference/copy/en/options/emitDeclarationOnly.md

@@ -0,0 +1,5 @@
+---
+display: "Emit Declaration Only"
+---
+
+Only emit '.d.ts' declaration files.

packages/tsconfig-reference/copy/en/options/emitDecoratorMetadata.md

@@ -0,0 +1,5 @@
+---
+display: "Emit Decorator Metadata"
+---
+
+Enables experimental support for emitting type metadata for decorators.

packages/tsconfig-reference/copy/en/options/esModuleInterop.md

@@ -0,0 +1,5 @@
+---
+display: "Es Module Interop"
+---
+
+Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'.

packages/tsconfig-reference/copy/en/options/experimentalDecorators.md

@@ -0,0 +1,5 @@
+---
+display: "Experimental Decorators"
+---
+
+Enables experimental support for ES7 decorators.

packages/tsconfig-reference/copy/en/options/extendedDiagnostics.md

@@ -0,0 +1,5 @@
+---
+display: "Extended Diagnostics"
+---
+
+Show verbose diagnostic information.

packages/tsconfig-reference/copy/en/options/forceConsistentCasingInFileNames.md

@@ -0,0 +1,5 @@
+---
+display: "Force Consistent Casing In File Names"
+---
+
+Disallow inconsistently-cased references to the same file.

packages/tsconfig-reference/copy/en/options/importHelpers.md

@@ -0,0 +1,5 @@
+---
+display: "Import Helpers"
+---
+
+Import emit helpers from 'tslib'.

packages/tsconfig-reference/copy/en/options/incremental.md

@@ -0,0 +1,5 @@
+---
+display: "Incremental"
+---
+
+Enable incremental compilation

packages/tsconfig-reference/copy/en/options/inlineSourceMap.md

@@ -0,0 +1,5 @@
+---
+display: "Inline Source Map"
+---
+
+Emit a single file with source maps instead of having a separate file.