npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

tsdoc-markdown

v0.6.3

Published

Generates markdown documentation from TypeScript source code.

Downloads

7,681

Readme

tsdoc-markdown

Generates markdown documentation from TypeScript source code. Useful for generating docs from code and injecting automatically the outcome into project README files.

npm license

All Contributors

:1234: Table of contents

:arrow_down: Installation

Install the library in your project from npm:

npm install -D tsdoc-markdown

:electric_plug: GitHub Actions

A GitHub Actions workflow that generates the documentation for pull requests using this library is available in tsdoc.yml.

:zap: Usage

This tool is shipped with a NodeJS bin script tsdoc that can be added to your package.json.

e.g. generating the documentation for a source file ./src/index.ts:

{
  "script": {
    "tsdoc": "tsdoc --src=src/index.ts"
  }
}

The --src parameter accepts a comma separated list of paths and wildcards as well.

e.g.

tsdoc --src=src/lib/*
tsdoc --src=src/lib/index.ts,src/lib/docs.ts

Note: the library exports per default only the documentation of the pattern you provide. It does not explore the TypeScript tree. If you wish to do so, either provide a PR to the Cli to support the option explore or create your own script for your project 😉

The Markdown documentation is parsed per default in a ./README.md that finds place where you started the command line. The output file will be over write unless you specify a TSDOC_START and TSDOC_END tag (as HTML comment). In such case, the documentation will be parsed within these two tags.

Specifying another output file is also supported with the parameter --dest.

To generate links to the documented source code, you can also provide the --repo parameter, which corresponds to the URL of your repository on GitHub.

This library generates Markdown documentation from TypeScript source code for Functions, Constants and Classes. Documentation for Interfaces and Types is not generated by default. To opt-in for types use the parameter --types.

Using above script is of course optional. You can also develop your own JavaScript script and use one of the functions here under.

e.g.

#!/usr/bin/env node

const {generateDocumentation} = require('tsdoc-markdown');

// Generate documentation for a list of files
const nnsInputFiles = [
  './packages/nns/src/account_identifier.ts',
  './packages/nns/src/genesis_token.canister.ts',
  './packages/nns/src/governance.canister.ts',
  './packages/nns/src/icp.ts'
];

generateDocumentation({
  inputFiles: nnsInputFiles,
  outputFile: './packages/nns/README.md'
});

// Start from a single file and explore the TypeScript tree

const utilsInputFiles = ['./packages/utils/src/index.ts'];

generateDocumentation({
  inputFiles: utilsInputFiles,
  outputFile: './packages/utils/YOLO.md',
  buildOptions: {
    explore: true,
    repo: {
      url: 'https://github.com/peterpeterparker/tsdoc-markdown'
    }
  }
});

// Generate documentation for types and interfaces as well

const utilsInputFiles = ['./packages/utils/src/index.ts'];

generateDocumentation({
  inputFiles: utilsInputFiles,
  outputFile: './packages/utils/YOLO.md',
  buildOptions: {
    types: true
  }
});

:toolbox: Functions

:gear: buildDocumentation

Build the documentation entries for the selected sources.

| Function | Type | | -------------------- | --------------------------------------------------------------------------------------------------------- | | buildDocumentation | ({ inputFiles, options }: { inputFiles: string[]; options?: BuildOptions or undefined; }) => DocEntry[] |

Parameters:

  • params.inputFiles: The list of files to scan and for which the documentation should be build.
  • params.options: Optional compiler options to generate the docs

:link: Source

:gear: documentationToMarkdown

Convert the documentation entries to an opinionated Markdown format.

| Function | Type | | ------------------------- | ---------------------------------------------------------------------------------------------------- | | documentationToMarkdown | ({ entries, options }: { entries: DocEntry[]; options?: MarkdownOptions or undefined; }) => string |

Parameters:

  • params.entries: The entries of the documentation (functions, constants and classes).
  • params.options: Optional configuration to render the Markdown content. See types.ts for details.

:link: Source

:gear: generateDocumentation

Generate documentation and write output to a file. If the file exists, it will try to insert the docs between and comments. If these does not exist, the output file will be overwritten.

| Function | Type | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | generateDocumentation | ({ inputFiles, outputFile, markdownOptions, buildOptions }: { inputFiles: string[]; outputFile: string; markdownOptions?: MarkdownOptions or undefined; buildOptions?: BuildOptions or undefined; }) => void |

Parameters:

  • params.inputFiles: The list of files to scan for documentation. Absolute or relative path.
  • params.outputFile: The file to output the documentation in Markdown.
  • params.markdownOptions: Optional settings passed to the Markdown parser. See MarkdownOptions for details.
  • params.buildOptions: Options to construct the documentation tree. See BuildOptions for details.

:link: Source

:books: Useful Resources

:sparkles: Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

:page_facing_up: License

MIT © David Dal Busco