Typescript inside `.vue` single component file about better-docs HOT 3 OPEN

Changing the regex to <script[^>]*>(.*?)</script> in component.js works:

var script = e.source.match(new RegExp('<script[^>]*>(.*?)</script>', 's'))

Additionally, in typescript.js you have to add .vue to the list of processed file extensions in the beforeParse function:

if (['.ts', '.tsx', '.vue'].includes(path.extname(e.filename))) {

Also pay attention to the order of the jsdoc plugins:

plugins: [
    "node_modules/better-docs/component",
    "node_modules/better-docs/typescript",
  ]

i.e. first split the single-file component, then transpile typescript.

from better-docs.

Hi,

It was painful for me to have generated documentation from Jsdoc format for a Vue project using typescript and under Windows. I don't think it's the good way of work but as it looks to work (at least for a simple example) I describe the steps. My wish is really that someone has enough skill (unlike me) to handle the point and allow generating documents just with a npm install better-docs.

1. Following packages have been retrieved in devDependecies (in addition of the existing ones)
   by adding the line in package.json (+ execution of #> npm install)

"devDependencies": {
    ...
    "better-docs": "^2.0.1",                                // The main package
    "@babel/core": "^7.9.6",                                // better-docs dependency
    "@babel/plugin-proposal-class-properties": "^7.8.3",    // Fix issue: Support for the experimental syntax 'classProperties' isn't currently enabled 
    "@babel/plugin-proposal-decorators": "^7.8.3",          // Fix issue: Support for the experimental syntax 'decorators-legacy' isn't currently enabled
    "babel-plugin-module-resolver": "^4.0.0",               // Fix issue: Cannot resolve dependency '@/plugins/...
    "parcel": "^1.12.4",                                    // better-docs dependency
    "cross-env": "^7.0.2",                                  // Just for Windows
}

2. As described above (thank you SMK), some better-docs scripts have been changed.
   TAKE CARE about this, because it can be lost by refreshing the node_modules.

$WorkspaceFolder\node_modules\better-docs\typescript.js: Fix the fact that vue files are not scanned.
if (['.ts', '.tsx', '.vue'].includes(path.extname(e.filename))) {

$WorkspaceFolder\node_modules\better-docs\component.js: Fix lang="ts" in vue files.
var script = e.source.match(new RegExp('<script[^>]*>(.*?)</script>', 's'))

$WorkspaceFolder\node_modules\better-docs\bundler.js (Windows only): Fix directory separator.

import VueWrapper from '${path.relative(absoluteOut, path.join(__dirname, VUE_WRAPPER)).replace(/\\/g, '/')}';\n
...
const cmd = `cross-env NODE_ENV=development parcel build ${entry} --out-dir ${outDist}`

3. A file named jsdoc-babel.json must be created
   This file will be used as configuration input by jsdoc:
   (Note that I tried to used jsdoc-babel)

{
    "opts": {
      "template": "node_modules/better-docs",
      "destination": "./docs/",
      "encoding": "utf8",
      "recurse": true
    },
    "tags": {
      "allowUnknownTags": ["optional", "component"]
    },
    "plugins": [
      "node_modules/better-docs/component",
      "node_modules/better-docs/typescript",
    ],
    "source": {
      "includePattern": "\\.(vue|jsx|js|ts|tsx)$",
      "exclude": [ "node_modules" ]
    },
}

4. A file named jsdoc-babelrc.json must be created.
   It will be used indirectly by parcel as a .babelrc file during the creation of documentation.
   Here I have a doubt on the proper way of work. It was just to make it worked.

{
  "presets": ["@babel/preset-env"], 
  "plugins": [ 
    ["@babel/plugin-proposal-decorators", { "decoratorsBeforeExport": true } ],
    "@babel/plugin-proposal-class-properties",
    [ "module-resolver", {
      "root": ["./"],
      "alias": {
        "@": "./src"
      }
    } ]
   ]
}

The module-resolver plugin is used there to fix the @ alias we can put in the import.

5. Then a command docs has been added to the package.json.
   This command :

• Copy the jsdoc-babelrc.json to .babelrc.json (TAKE CARE TO ADAPT if you have already a .babelrc into the root directory).
• Launch the jsdoc compilation with the file jsdoc-babel.json as input
• Remove the file .babelrc.json

package.json for Windows:

"scripts": {
  ...
  "docs": "PowerShell -Command \"& {cp jsdoc-babelrc.json .babelrc}\"; jsdoc -c jsdoc-babel.json ./src; Remove-Item .babelrc ",
}

package.json for Others (I suppose, without powershell):

"scripts": {
  ...
  "docs": "cp jsdoc-babelrc.json .babelrc && jsdoc -c jsdoc-babel.json ./src && rm .babelrc",
}

Yes, it's the only way I found. Because parcel is not taking the balbel.config.json file
And when I put everything in the .babelrc with all additional plugins then documentation is ok but it's my project which does not compile anymore :D

My understading is that even if it's working, the different layer of transpilation are not the same for my documentation and my project.
So I suppose that's ok for my little example, but I'm not sure for bigger projects.

6. Finally, we run the command:
   #> npm run docs

7. And after all of that, if you're lucky, the documentation is generated into the folder docs.

Note that I was not able to make the @component of better-doc working correctly but only generate from jsdoc format.

I wish it could help.
Best Regards.

from better-docs.

Just in addition,

Before to go further, may the choice of the document generator can save time if you don't need jsdoc format.
I have searched document generator for vue. But all of them are not handling vue+typescript+jsdoc format. Only better-docs was the more ready for that (I found it with this article)

I invite people to read this vue community article.

Here a trend of the different document generators I found (there is many others).

jsdoc alone and typedoc don't work currently for my purpose. I was not able able to make tsdoc working (if someone has an example for vue). Styleguide was cool for the component but I was not able to handle my store ts files (even if it looks to support vuex) and I was not able to make it worked with backend/frontend logic.

For storybook, it looks more and more famous but I don't find what I want:

• Prototype description (with type)

If someone has any solution, it's welcome.

from better-docs.