8000 GitHub - wulunyi/vuese: 🤗 Your vue SFC is your document - Parsing Vue SFC and generating documentation.
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content
/ vuese Public
forked from vuese/vuese

🤗 Your vue SFC is your document - Parsing Vue SFC and generating documentation.

0 stars 116 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

wulunyi/vuese

BranchesTags
 
 

Repository files navigation

vuese

Your vue SFC is your document - Parsing Vue SFC and generating documentation.

Status

build status

Install

yarn global add vuese

Table of contents

Features

  • Identify name, props, events, slots, methods and generate corresponding markdown content.

  • Generate markdown files.

  • Document integration: generate a docute document.

  • Annotation enhancement (@xxx).

  • cli & Core module for nodejs.

  • Support ts & vue-class-component & vue-property-decorator

  • Support for slots in render function.

  • Identify v-model

Usage

Basic

Previously: When you created a Vue component, you needed to manually write the documentation, including the components' props, events, slots, and some methods.

Now: If you created the following components.

<template>
  <div>
    <!-- Form header -->
    <slot name="header">
      <!-- `<th>title</th>` -->
      <th>title</th>
    </slot>
  </div>
</template>

<script>
export default {
  props: {
    // The name of the form, up to 8 characters
    name: {
      type: [String, Number],
      required: true,
      validator () {}
    }
  },
  methods: {
    // @vuese
    // Used to manually clear the form
    clear () {
      // Fire when the form is cleared
      // @arg The argument is a boolean value representing xxx
      this.$emit('onclear', true)
    }
  }
}
</script>

We assume that the above component is components/comp.vue, then you only need to execute the following command:

vuese gen --include="components/*.vue"

Then you can choose which type of document to generate: just markdown or generate a docute document:

If you choose to generate a docute document, the document will be output in your command execution directory. At this point you can execute the following command:

vuese serve --open

It will launch a document server and automatically open the browser, as shown below:

Use configuration file

vuese will search vuese.config.js or .vueserc or vuese property in package.json from your base directory. The following options can be used both on the command line and in the configuration file.

include

  • Type: string string[]
  • Default: ["**/*.vue"]

Specify which .vue files need to be generated, and by default include all .vue files in the current directory and subdirectories.

exclude

  • Type: string string[]
  • Default: []

Specify which .vue files do not need to be documented. Note: node_modules/**/*.vue is excluded by default.

outDir

  • Type: string
  • Default: website

Output directory of the docute document.

markdownDir

  • Type: string
  • Default: components

The output directory of the markdown file, note: markdownDir is based on outdir, which means that the markdown file will be output to the website/components directory.

genType

  • Type: string
  • Default: ''

Select the target to generate, can be either 'docute' or 'markdown', if you don't specify genType, vuese will ask you 😋.

title

  • Type: string
  • Default: ''

If you want to generate a docute document, you need to specify the sidbar title, if you don't specify title, vuese will ask you too 😋.

Used in nodejs

vuese exposes two modules: parser and Render.

parser

ParserResult

The parser function receives the contents of the .vue source file as the first argument, parses the string and gets the parsed result:

const { parser } = require('vuese')
// Read .vue source files
fs.readFile(abs, 'utf-8')
  .then(source => {
    const parserRes = parser(source)
  })
interface ParserResult {
  props?: PropsResult[]
  events?: EventResult[]
  slots?: SlotResult[]
  methods?: MethodResult[]
  name?: string
}
ParserOptions

You can pass the second argument as a parsing option:

interface ParserOptions {
  onProp?: {
    (propsRes?: PropsResult[]): any
  }
  onEvent?: {
    (eventRes?: EventResult): any
  }
  onMethod?: {
    (methodRes?: MethodResult): any
  }
  onSlot?: {
    (slotRes?: SlotResult): any
  }
  onName?: {
    (name: string): any
  }
  babelParserPlugins?: ParserPlugin[]
}

The default parsing option is:

const defaultOptions: ParserOptions = {
  onName(name: string) {
    res.name = name
  },
  onProp(propsRes?: PropsResult[]) {
    if (propsRes) {
      res.props = propsRes
    }
  },
  onEvent(eventsRes?: EventResult) {
    if (eventsRes) {
      ;(res.events || (res.events = [])).push(eventsRes)
    }
  },
  onSlot(slotRes?: SlotResult) {
    if (slotRes) {
      ;(res.slots || (res.slots = [])).push(slotRes)
    }
  },
  onMethod(methodRes?: MethodResult) {
    if (methodRes) {
      ;(res.methods || (res.methods = [])).push(methodRes)
    }
  },
  babelParserPlugins: ['objectRestSpread', 'dynamicImport']
}

Render

Render is a class that creates a render instance that receives the parsing result as a parameter:

const r = new Render(parserRes)
const renderRes = r.render()
RenderResult
interface RenderResult {
  props?: string
  slots?: string
  events?: string
  methods?: string
}

Write a document for your component

The process of writing a document is to write a comment for your code.

props

Assume we have a prop called name:

props: {
  name: {
    type: String
  }
}

When there are no comments, the generated document is as follows:

Name Description Type Required Default
name - String false -

We noticed that the prop named name is not described, in this case, we only need to add leading comments to the name attribute:

props: {
  // The name of the form
  name: {
    type: String
  }
}

In this way, the description of the prop will be included in the document, as shown below:

Name Description Type Required Default
name The name of the form String false -

In addition, we also notice that the type of prop called name is automatically obtained from the type attribute, but sometimes we need to show the user a more explicit choice, then we only need to add leading comments to the type attribute, as shown below:

props: {
  // The name of the form
  name: {
    // `'TOP'` / `'BOTTOM'`
    type: String
  }
}

The generated document is as follows:

Name Description Type Required Default
name The name of the form 'TOP' / 'BOTTOM' false -

Similarly, we can specify default values:

props: {
  // The name of the form
  name: {
    // `'TOP'` / `'BOTTOM'`
    type: String,
    required: true,
    default: 'TOP'
  }
}

Then we get:

Name Description Type Required Default
name The name of the form 'TOP' / 'BOTTOM' true 'TOP'

Note: You can also add leading comments to the default attribute.

slots

Assume we have the following template which contains a named slot and default slot content:

<slot name="header">
  <th>title</th>
</slot>

The generated document is as follows:

Name Description Default Slot Content
header - -

We can see that the slot called header is not described, and there is no description of the default slot content.

Then we add a comment to it:

<!-- Form header -->
<slot name="header">
  <!-- `<th>title</th>` -->
  <th>title</th>
</slot>

Then we get:

Name Description Default Slot Content
header Form header <th>title</th>

Sometimes we will encounter nested slots:

<!-- Form header -->
<slot name="header">
  <!-- `<th>title</th>` -->
  <slot name="defaultHeader"></slot>
</slot>

Note: At this point, the comment content <!-- `<th>title</th>` --> is not a description of the slot called defaultHeader. It is still a description of the default slot contents of the slot called header.

In order to add a description to the slot called defaultHeader, we need to add another comment:

<!-- Form header -->
<slot name="header">
  <!-- `<th>title</th>` -->
  <!-- Custom form header -->
  <slot name="defaultHeader"></slot>
</slot>

Then we get:

Name Description Default Slot Content
header Form header <th>title</th>
defaultHeader Custom form header -

events

Note: Vuese only treats this.$emit() as an event

Assume we have the following code:

methods: {
  clear () {
    this.$emit('onclear')
  }
}

The generated document is as follows:

Event Name Description Parameters
onclear - -

Just add leading comments to it:

methods: {
  clear () {
    // Fire when the form is cleared
    this.$emit('onclear', true)
  }
}

Then we get:

Event Name Description Parameters
onclear Fire when the form is cleared -

If you want to describe the parameters further, you need to use the @arg identifier:

methods: {
  clear () {
    // Fire when the form is cleared
    // @arg The argument is a boolean value representing xxx
    this.$emit('onclear', true)
  }
}

Then we get:

Event Name Description Parameters
onclear Fire when the form is cleared The argument is a boolean value representing xxx

methods

Similar to events, but with one difference, since not all methods need to be exposed to the developer, you need to use the @vuese flag to tell vuese which methods are needed to generate the document:

methods: {
  /**
   * @vuese
   * Used to manually clear the form
   * @arg The argument is a boolean value representing xxx
   */
  clear (bol) {
    // ...
  }
}

Then we get:

Method Description Parameters
clear Used to manually clear the form The argument is a boolean value representing xxx

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D

Author

vuese © HcySunYang, Released under the MIT 54C4 License.
Authored and maintained by HcySunYang.

hcysun.me · GitHub @HcySunYang · Twitter @HcySunYang

About

🤗 Your vue SFC is your document - Parsing Vue SFC and generating documentation.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 56.6%
  • CSS 20.7%
  • JavaScript 13.7%
  • Vue 6.5%
  • HTML 2.5%
0