@vuedoc/md
Generate a Markdown Documentation for a Vue file component
Last updated 23 days ago by demsking .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @vuedoc/md 
SYNC missed versions from official npm registry.

Vuedoc Markdown Documentation Generator

Generate a Markdown Documentation for a Vue file

npm Build status Test coverage

Table of Contents

Install

# using in your project
npm install --save @vuedoc/parser @vuedoc/md

# using in command line
npm install --global @vuedoc/parser @vuedoc/md

Features

  • Generate documentation for component props
  • Generate documentation for component data
  • Generate documentation for computed properties with their dependencies
  • Generate documentation for component events
  • Generate documentation for component slots
  • Generate documentation for component methods
  • Support of JSDoc

Command line usage

# display the vuedoc.md version
vuedoc.md --version

# this print documentation in the standard output
vuedoc.md components/textarea.vue

# generate a Markdown documentation in a file docs/textarea.md
vuedoc.md components/textarea.vue --output docs/

# generate a Markdown documentation all components
vuedoc.md components/*.vue --output docs/

# update the API section of README.md with generated documentation
vuedoc.md components/textarea.vue --section "API" --output README.md

# combine generated documentations of all components into one
vuedoc.md --join components/*.vue --output README.md

# using pipe
cat components/textarea.vue | vuedoc.md

Bellow an output sample of test/fixtures/textarea.example.vue:

# MyTextarea

The custom HTML `<textarea>` component.

- **author** - Arya Stark
- **license** - MIT

## Slots

| Name      | Description                             |
| --------- | --------------------------------------- |
| `label`   | Use this slot to set the label          |
| `default` | Use this slot to set the textarea value |

## Props

| Name            | Type      | Description                                                                                                                                                  | Default                      |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| `v-model`       | `String`  | Use this directive to create two-way data bindings with the component. It automatically picks the correct way to update the element based on the input type. |                              |
| `id` *required* | `String`  | Defines a unique identifier (ID) which must be unique in the whole document.                                                                                 |                              |
| `disabled`      | `Boolean` | This Boolean property indicates that the user cannot interact with the control.                                                                              | `false`                      |
| `theme`         | `Object`  | Define a custom theme for the component.                                                                                                                     | `new DefaultTextareaTheme()` |

## Events

| Name    | Description                                                                                                                                                                                                                                                                                                                                     |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input` | Fired when the value is changed.<br>**Arguments**<br><ul><li>**`value: string`** — The updated value</li></ul>                                                                                                                                                                                                                                  |
| `keyup` | Fired when a key is released.<br>**Arguments**<br><ul><li>**`event: KeyboardEvent`** — Object describes a user interaction with the keyboard</li><li>**`event.code: DOMString`** — The code value of the physical key represented by the event</li><li>**`event.key: DOMString`** — The key value of the key represented by the event</li></ul> |

## Methods

### Textarea.replace()

The `replace()` method returns a new string with some or all matches of
a `pattern` replaced by a `replacement`. The `pattern` can be a string
or a RegExp, and the `replacement` can be a string or a function to be
called for each match. If `pattern` is a string, only the first
occurrence will be replaced.

The original string is left unchanged.

**Example**

```js
const p = 'The quick brown fox jumps over the lazy dog. If the dog reacted, was it really lazy?';
const regex = /dog/gi;

console.log(p.replace(regex, 'ferret'));
// expected output: "The quick brown fox jumps over the lazy ferret. If the ferret reacted, was it really lazy?"

console.log(p.replace('dog', 'monkey'));
// expected output: "The quick brown fox jumps over the lazy monkey. If the dog reacted, was it really lazy?"
```

**Syntax**

```ts
const newStr = str.replace(pattern|substr, newSubstr|callback)
```

**Parameters**

- **`pattern: RegExp`**<br>
  A RegExp object or literal. The match or matches are replaced with newSubstr or the value returned by the specified function.

- **`substr: String`**<br>
  A String that is to be replaced by newSubstr. It is treated as a literal string and is not interpreted as a regular expression. Only the first occurrence will be replaced.

- **`newSubstr: String`**<br>
  The String that replaces the substring specified by the specified regexp or substr parameter. A number of special replacement patterns are supported; see the "Specifying a string as a parameter" section below.

- **`callback: Function`**<br>
  A function to be invoked to create the new substring to be used to replace the matches to the given regexp or substr. The arguments supplied to this function are described in the "Specifying a function as a parameter" section below.

**Return value**

A new string, with some or all matches of a pattern replaced by a replacement.

Command line options

--join                   # Combine generated documentation for multiple component files into only one
--stringify [boolean]    # Set to `false` to disable parsing of litteral values and stringify litteral values. Default: `true`
--level [integer]        # Set the title level. An integer between 1 and 6
--output [file or dir]   # The output directory. If absent, the STDOUT will be used
--section [section name] # Inject the generated documentation to a section. Works with `--output file`
--ignore-name            # Ignore the component name on parsing
--ignore-description     # Ignore the component description on parsing
--ignore-keywords        # Ignore the component keywords on parsing
--ignore-slots           # Ignore the component slots on parsing
--ignore-props           # Ignore the component props on parsing
--ignore-computed        # Ignore the component computed properties on parsing
--ignore-data            # Ignore the component data on parsing
--ignore-methods         # Ignore the component methods on parsing
--ignore-events          # Ignore the component events on parsing

Programmatic Usage

Options

Name Type Description
level Integer Set the title level. An integer between 1 and 6
output String The output of the documentation. Can be a directory or a Markdown file. If absent, the STDOUT will be used
section String Inject the generated documentation to a section. Works with options.output as Markdown file output
join Boolean Combine generated documentation for multiple component files into only one

For parsing options please read the Vuedoc Parser documentation

Usage

const vuedoc = require('@vuedoc/md')
const options = {
  filename: 'test/fixtures/checkbox.vue'
}

vuedoc.md(options)
  .then((document) => console.log(document))
  .catch((err) => console.error(err))

Documentation Syntax

For the complete documentation syntax, please follow this link:

Visibility Keywords

Keywords Description
@public By default all commented members are public; this means they will be part of the documented members
@protected Commented members with this will be ignored
@private Commented members with this will be ignored

Example

export default {
  name: 'CheckboxInput',
  props: {
    /**
     * The input format callback
     * @public
     */
    format: Function
  },
  methods: {
    /**
     * This will be ignored on parsing and rendering
     * @private
     */
    validate() {},
    /**
     * This will be ignored on parsing and rendering
     * @protected
     */
    commit() {}
  }
}

Specific Keywords for Props

  • @type {typeName}: Commented prop will use provided type name as type instead of type in source code. This option may be helpful in case the prop type is an object or a function, which you may want to further detail with @typedef in another place

  • @default {value}: Commented prop will use the provided value as default prop description. This option may be helpful in case the prop type is an object or function

Example

export default {
  name: 'TextInput',
  props: {
    /**
     * The input format callback
     * @type TextInput.FormatCallback
     * @default value.trim()
     */
    format: {
      type: Function,
      default: (value = '') => `${value}`.trim()
    }
  }
}

Specific Keywords for Methods

  • @method {name}: Use this to set a custom method name
  • @syntax {string}: Use this to set a custom method syntax

Example

export default {
  name: 'TextInput',
  methods: {
    /**
     * This use `@method` to set a custom method name and syntax
     * @method String.prototype.match
     * @syntax str.match(regexp)
     */
    match(regexp) {},
    /**
     * Multiple `@syntax` keywords can be used to define a multiline syntax content
     * @syntax target.addEventListener(type, listener [, options]);
     * @syntax target.addEventListener(type, listener [, useCapture]);
     * @syntax target.addEventListener(type, listener [, useCapture, wantsUntrusted  ]); // Gecko/Mozilla only
     */
    addEventListener(type, listener, options, useCapture) {}
  }
}

Examples

Vuedoc Markdown has been used to generate documentation of bellow components:

Generate a documentation for an SFC component

Component file Markdown output
test/fixtures/checkbox.example.vue test/fixtures/checkbox.output.md
test/fixtures/textarea.example.vue test/fixtures/textarea.output.md

Generate a MDN-like documentation for a method

Component file Markdown output
test/fixtures/mdn.event.example.vue test/fixtures/mdn.event.output.md
test/fixtures/mdn.string.example.vue test/fixtures/mdn.string.output.md
test/fixtures/mdn.regexp.example.vue test/fixtures/mdn.regexp.output.md

Find more examples here: test/fixtures

Related projects

Contribute

Contributions to Vuedoc Markdown are welcome. Here is how you can contribute:

  1. Submit bugs or a feature request and help us verify fixes as they are checked in
  2. Create your working branch from the dev branch: git checkout dev -b feature/my-awesome-feature
  3. Install development dependencies: npm run install:dev
  4. Write code for a bug fix or for your new awesome feature
  5. Write test cases for your changes
  6. Submit merge requests for bug fixes and features and discuss existing proposals

Versioning

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

See SemVer.org for more details.

License

Under the MIT license. See LICENSE file for more details.

Current Tags

  • 2.0.0-beta2                                ...           latest (23 days ago)

31 Versions

  • 2.0.0-beta2                                ...           23 days ago
  • 2.0.0-beta1                                ...           2 months ago
  • 1.6.0                                ...           2 years ago
  • 1.5.0                                ...           2 years ago
  • 1.4.1                                ...           2 years ago
  • 1.4.0                                ...           2 years ago
  • 1.3.3                                ...           2 years ago
  • 1.3.2                                ...           2 years ago
  • 1.3.1                                ...           2 years ago
  • 1.3.0                                ...           2 years ago
  • 1.2.2                                ...           2 years ago
  • 1.1.1                                ...           2 years ago
  • 1.1.0                                ...           2 years ago
  • 1.0.1                                ...           3 years ago
  • 1.0.0                                ...           3 years ago
  • 0.8.2                                ...           3 years ago
  • 0.8.1                                ...           3 years ago
  • 0.8.0                                ...           3 years ago
  • 0.7.1                                ...           3 years ago
  • 0.7.0                                ...           3 years ago
  • 0.6.0                                ...           3 years ago
  • 0.5.0                                ...           3 years ago
  • 0.4.0                                ...           3 years ago
  • 0.3.4                                ...           3 years ago
  • 0.3.3                                ...           3 years ago
  • 0.3.2                                ...           3 years ago
  • 0.3.0                                ...           3 years ago
  • 0.2.0                                ...           3 years ago
  • 0.1.3                                ...           3 years ago
  • 0.1.2                                ...           3 years ago
  • 0.1.1                                ...           3 years ago
Maintainers (1)
Downloads
Today 0
This Week 15
This Month 15
Last Day 3
Last Week 42
Last Month 165
Dependencies (6)
Dev Dependencies (7)

Copyright 2014 - 2016 © taobao.org |