https://github.com/metonym/hindsight

Generate prop documentation for Svelte components
https://github.com/metonym/hindsight

Last synced: about 1 month ago
JSON representation

Generate prop documentation for Svelte components

• Host: GitHub
• URL: https://github.com/metonym/hindsight
• Owner: metonym
• License: mit
• Created: 2020-03-31T00:50:19.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2020-03-31T13:49:35.000Z (over 4 years ago)
• Last Synced: 2024-09-14T00:18:23.236Z (2 months ago)
• Language: TypeScript
• Size: 16.6 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# hindsight

> Generate prop documentation for Svelte components.

**NOTE** This is a work in progress. See the [v0.1.0 project roadmap](https://github.com/metonym/hindsight/projects/1).

The aim of this project is to quickly generate documentation for a Svelte component given its exported properties. The output format could be text, markdown or JSON.

## Motivation

The easiest way to annotate a component property is to write a trailing comment.

In the following example, we know there are three possible values for `kind`: "primary," "secondary" or "tertiary." We also know that "primary" is the default value.

```html

  export let kind = "primary"; // 'primary' | 'secondary' | 'tertiary'

```

As a compiler, svelte supports parsing and walking components as an AST. Therefore, it is straightforward to extract trailing comments for a writable variable declaration.

## Approach

The input is a glob of svelte components. For each component:

1. **Collect writable variables** (i.e. `let`) using the `svelte.compile` API

2. **Parse component as an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)** using the `svelte.parse` API

3. **Walk the AST** and annotate types (prop name/value/default value)

## Quick Start

```bash

npx hindsight 'src/**/*.svelte'

```

## Usage

### CLI

```bash

yarn add -D hindsight

yarn run hindsight 'src/**/*.svelte'

```

### Node.js

```js

const hindsight = require("hindsight");

(async () => {

  const types = await hindsight({ include: ["temp/**/*.{svelte,html}"] });

})();

```

## License

[MIT](LICENSE)