docs-ts

title: Contents 
style: nestedList # TOC style (nestedList|inlineFirstLevel)
minLevel: 1 # Include headings from the specified level
maxLevel: 4 # Include headings up to the specified level
includeLinks: true # Make headings clickable
debugInConsole: false # Print debug info in Obsidian console

Overview

Sources:

Creating and maintaining 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:

TagDescriptionDefault
@categoryGroups associated module exports together in the generated documentation.'utils'
@exampleAllows 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).
@sinceAllows for documenting most recent library version in which a given piece of source code was updated.
@deprecatedMarks source code as deprecated, which will strikethrough the name of the annotated module or function in the generated documentation.false
@internalPrevents 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.
@ignorePrevents 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.0
 

Configuration

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>
  readonly compilerOptions?: Record<string, unknown>
}

The following table describes each configuration parameter, its purpose, and its default value.

ParameterDescriptionDefault Value
projectHomepageWill link to the project homepage from the Auxiliary Links of the generated documentation.homepage in package.json
srcDirThe directory in which docs-ts will search for TypeScript files to parse.'src'
outDirThe directory to which docs-ts will generate its output markdown documents.'docs'
themeThe theme that docs-ts will specify should be used for GitHub Docs in the generated _config.yml file.'pmarsceill/just-the-docs'
enableSearchWhether or search should be enabled for GitHub Docs in the generated _config.yml file.true
enforceDescriptionsWhether or not descriptions for each module export should be required.false
enforceExamplesWhether or not @example tags for each module export should be required. (Note: examples will not be enforced in module documentation)false
enforceVersionWhether or not @since tags for each module export should be required.true
excludeAn array of glob strings specifying files that should be excluded from the documentation.[]
parseCompilerOptionstsconfig for parsing options{}
examplesCompilerOptionstsconfig for the examples options{}

Appendix

Note created on 2024-04-15 and last modified on 2024-04-15.

LIST FROM [[Tool - docs-ts]] AND -"CHANGELOG" AND -"04-RESOURCES/Tools/Tool - docs-ts"

(c) No Clocks, LLC | 2024