search

KatChaotic / sveltedoc-parser

Generate a JSON documentation for a Svelte (https://github.com/sveltejs/svelte) component
https://www.npmjs.com/package/sveltedoc-parser
MIT License
90 stars 7 forks source link
docs jsdoc parser svelte svelte-documentation sveltejs

readme

The sveltedoc parser

Generate a JSON documentation for a Svelte file.

npm GitHub Workflow Status (branch)

Table of Contents

Changelog

[4.2.1] 15.12.2021

[4.2.0] 14.12.2021

[4.1.0] 19.02.2021

Thanks a lot @soft-decay for contributing in this release!

[4.0.0] 25.01.2021

Full changelog of release versions can be found here.

Install

npm install --save sveltedoc-parser

Features

Common

Svelte 2

Svelte 3

Options

The options object passed to the parse function must include filename or fileContent.

Here are the properties supported by options (see the Usage section below):

json Path Description Type Default value
filename The filename to parse. Required, unless fileContent is passed. string
fileContent The file content to parse. Required, unless filename is passed. string
encoding The file encoding. string utf8
features The component features to parse and extract. string[] All supported features
ignoredVisibilities The list of ignored visibilities. Symbols with a visibility that is ignored will not be included in the output. string[] ['private', 'protected']
includeSourceLocations Flag, which indicates that source locations should be provided for component symbols. boolean false
version Optional. Use 2 or 3 to specify which svelte syntax should be used. When that is not provided, parser try to detect version of the syntax. number? undefined
defaultVersion Optional. Specify default version of svelte syntax, if auto-detector can't identify correct version. number? undefined

Supported feature names

These are the values that can be included in the options.features array:

Feature Svelte 2 Svelte 3 Description
name ✔ ✔ Component's name
description ✔ ✔ Component's description
keywords ✔ ✔ List of JSDoc keywords found in the top level comment
components ✔ ✔ List of imported components
computed ✔ ✔ List of computed properties
data ✔ ✔ List of data properties (Component's props)
events ✔ ✔ List of events fired/dispatched by this component
methods ✔ ✔ List of methods
refs ✔ ✔ List of references used by this component
slots ✔ ✔ List of slots provided by this component
actions ✔ List of actions
helpers ✔ List of helpers
transitions ✔ List of transitions used by this component
store NOT SUPPORTED

Output format

Output format is described in this document.

For Svelte 3 examples, take a look at the examples folder to check how Svelte 3 components are transformed to JSON documents.

For a Svelte 2 example, take a look at the JSON output generated from this component.

Usage

Minimal example:

const sveltedoc = require('sveltedoc-parser');
const options = {
    filename: 'main.svelte'
};

sveltedoc.parse(options)
    .then(componentDoc => {
        console.log(componentDoc);
    })
    .catch(e => {
        console.error(e);
    });

or with options customization:

const { parse } = require('sveltedoc-parser');
const { externalFileContent } = require('./local-file');
const options = {
    fileContent: externalFileContent,
    encoding: 'ascii',
    features: ['data', 'computed', 'methods'],
    ignoredVisibilities: ['private'],
    includeSourceLocations: true,
    version: 3
};
const doc = await parse(options);
console.log(doc)

API

parse(options)

Method to parse svelte component and provide doc object structure with details information.

detectVersion(options)

Method to detect the Svelte syntax used in the component. It returns, in order:

Issues

A list of known issues can be found here.

Found a new issue? Please contribute and write a detailed description here.

Contributors

Author Alexey Mulyukin

Inspired by Vuedoc Parser

License

MIT