@ericcrosson/docs-ts v1.0.1
Table of contents
A simple, opinionated, zero-configuration tool for creating beautiful documentation for TypeScript projects.
:warning: DISCLAIMER :warning:
docs-ts is used primarily as an opinionated documentation tool for libraries in the fp-ts ecosystem. The structure of source code documentation expected by docs-ts can be best understood by reviewing the source code of the fp-ts repository.
Installation:
Via npm
npm install -D docs-tsVia yarn
yarn add -D docs-tsVia npx (on-demand)
npx docs-tsWhy
Creating and maintaing documentation for a TypeScript project of any size can quickly become a herculean task. docs-ts simplifies this process by allowing you to co-locate your documentation with its associated code. You simply annotate your code with JSDoc comments, and then the CLI will generate beautiful markdown documents containing all of the documentation and examples you associated with your code. In addition, the generated output of docs-ts can be used as a publishing source for your repository's documentation on GitHub.
Usage
Using docs-ts is as simple as annotating your code with JSDoc comments. Specialized JSDoc tags can be used to perform various functions, such as grouping associated code together, versioning documentation, and running and testing source code. A full list of supported JSDoc tags can be found below.
Supported JSDoc Tags
| Tag | Description | Default |
|---|---|---|
@category | Groups associated module exports together in the generated documentation. | 'utils' |
@example | Allows usage examples to be provided for your source code. All examples are type checked using ts-node. Examples are also run using ts-node and the NodeJS assert module can be used for on-the-fly testing (see example below). | |
@since | Allows for documenting most recent library version in which a given piece of source code was updated. | |
@deprecated | Marks source code as deprecated, which will | false |
@internal | Prevents docs-ts from generating documentation for the annotated block of code. Additionally, if the stripInternal flag is set to true in tsconfig.json, TypeScript will not emit declarations for the annotated code. | |
@ignore | Prevents docs-ts from generating documentation for the annotated block of code. |
By default, docs-ts will search for files in the src directory and will output generated files into a docs directory. For information on how to configure docs-ts, see the Configuration section below.
Example
The best usage examples of docs-ts can be found in fp-ts ecosystem libraries that generate their documentation with docs-ts, such as the main fp-ts repository.
To illustrate the power of docs-ts, here is a small example. Running npm run docs-ts (or yarn docs-ts) in the root directory of a project containing the following file in the src directory...
/**
* @since 0.2.0
*/
import { log } from 'fp-ts/Console'
import { IO } from 'fp-ts/IO'
/**
* Greets a person by name.
*
* @example
* import { sayHello } from 'docs-ts/lib/greetings'
*
* assert.strictEqual(sayHello('Test')(), 'Hello, Test!')
* // => This assert statement will be run by docs-ts so you can test your code on-the-fly.
*
* @category greetings
* @since 0.6.0
*/
export const sayHello = (name: string): IO<void> => log(`Hello, ${name}!`)...will, by default, produce a docs directory containing the following markdown document in the modules subfolder.
---
title: greetings.ts
nav_order: 0
parent: Modules
---
## greetings overview
Added in v0.2.0
---
<h2 class="text-delta">Table of contents</h2>
- [greetings](#greetings)
- [sayHello](#sayhello)
---
# greetings
## sayHello
Greets a person by name.
**Signature**
```ts
export declare const sayHello: (name: string) => IO<void>
```
**Example**
```ts
import { sayHello } from 'docs-ts/lib/greetings'
assert.strictEqual(sayHello('Test')(), 'Hello, Test!')
```
Added in v0.6.0Configuration
docs-ts is meant to be a zero-configuration command-line tool by default. However, there are several configuration settings that can be specified for docs-ts. To customize the configuration of docs-ts, create a docs-ts.json file in the root directory of your project and indicate the custom configuration parameters that the tool should use when generating documentation.
The docs-ts.json configuration file adheres to the following interface:
interface Config {
readonly projectHomepage?: string
readonly srcDir?: string
readonly outDir?: string
readonly theme?: string
readonly enableSearch?: boolean
readonly enforceDescriptions?: boolean
readonly enforceExamples?: boolean
readonly enforceVersion?: boolean
readonly exclude?: ReadonlyArray<string>
}The following table describes each configuration parameter, its purpose, and its default value.
| Parameter | Description | Default Value |
|---|---|---|
| projectHomepage | Will link to the project homepage from the Auxiliary Links of the generated documentation. | homepage in package.json |
| srcDir | The directory in which docs-ts will search for TypeScript files to parse. | 'src' |
| outDir | The directory to which docs-ts will generate its output markdown documents. | 'docs' |
| theme | The theme that docs-ts will specify should be used for GitHub Docs in the generated _config.yml file. | 'pmarsceill/just-the-docs' |
| enableSearch | Whether or search should be enabled for GitHub Docs in the generated _config.yml file. | true |
| enforceDescriptions | Whether or not descriptions for each module export should be required. | false |
| enforceExamples | Whether or not @example tags for each module export should be required. (Note: examples will not be enforced in module documentation) | false |
| enforceVersion | Whether or not @since tags for each module export should be required. | true |
| exclude | An array of glob strings specifying files that should be excluded from the documentation. | [] |
Documentation
FAQ
Q: For functions that have overloaded definitions, is it possible to document each overload separately?
A: No, docs-ts will use the documentation provided for the first overload of a function in its generated output.
License
The MIT License (MIT)
2 years ago