better-docs 错误地创建了 entry.js 文件

Question

我尝试使用 jsDoc 的 better-docs 插件通过这个 link 为我的 react.js 项目制作文档：https://medium.com/@wojciechkrysiak/document-reactjs-components-with-preview-by-using-jsdoc-70d39d2cc777.

当我运行使用以下命令创建我的文档时：

npm run docs

我收到这个错误：

×  A:\dev\project\React\Hoko\docs\entry.js:25:25: Cannot resolve dependency '../../A:devprojectReactHokosrccomponentsanalyticsAnalyticsNavbar.jsx' at 'A:\dev\project\React\A:devprojectReactHokosrccomponentsanalyticsAnalyticsNavbar.jsx'
  23 |     import './styles/iframe.css';
  24 |
> 25 |   import Component0 from '../../A:\dev\project\React\Hoko\src\components\analytics\AnalyticsNavbar.jsx';
     |                         ^
  26 | reactComponents['AnalyticsNavbar'] = Component0;

A:\dev\project\React\Hoko\node_modules\better-docs\bundler.js:83
    throw error
    ^

Error: Command failed: parcel build docs\/entry.js --out-dir docs\/build
Browserslist: caniuse-lite is outdated. Please run next command `npm update caniuse-lite browserslist`
Browserslist: caniuse-lite is outdated. Please run next command `npm update caniuse-lite browserslist`
Browserslist: caniuse-lite is outdated. Please run next command `npm update caniuse-lite browserslist`

    at checkExecSyncError (child_process.js:611:11)
    at execSync (child_process.js:648:13)
    at bundle (A:\dev\project\React\Hoko\node_modules\better-docs\bundler.js:78:5)
    at Object.exports.publish (A:\dev\project\React\Hoko\node_modules\better-docs\publish.js:655:5)
    at Object.module.exports.cli.generateDocs (A:\dev\project\React\Hoko\node_modules\jsdoc\cli.js:441:39)
    at Object.module.exports.cli.processParseResults (A:\dev\project\React\Hoko\node_modules\jsdoc\cli.js:392:24)
    at module.exports.cli.main (A:\dev\project\React\Hoko\node_modules\jsdoc\cli.js:235:18)
    at Object.module.exports.cli.runCommand.cb [as runCommand] (A:\dev\project\React\Hoko\node_modules\jsdoc\cli.js:186:9)
    at A:\dev\project\React\Hoko\node_modules\jsdoc\jsdoc.js:93:9
    at Object.<anonymous> (A:\dev\project\React\Hoko\node_modules\jsdoc\jsdoc.js:94:3)
    at Module._compile (internal/modules/cjs/loader.js:688:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:699:10)
    at Module.load (internal/modules/cjs/loader.js:598:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:537:12)
    at Function.Module._load (internal/modules/cjs/loader.js:529:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:741:12)

如最上面的错误所示，问题来自我的组件的错误寻址：

'../../A:devprojectReactHokosrccomponentsanalyticsAnalyticsNavbar.jsx'

没有'/'字符！

我发现这个错误的地址也存在于 docs 文件夹的 entry.js 文件中。使用“\”而不是“/”。

entry.js:

    window.reactComponents = {};

    window.vueComponents = {};


      import React from "react";

      import ReactDOM from "react-dom";


      import ReactWrapper from '../../A:\dev\project\React\Hoko\node_modules\better-docs/lib/react-wrapper.js';

      window.React = React;

      window.ReactDOM = ReactDOM;

      window.ReactWrapper = ReactWrapper;


    import './styles/reset.css';

    import './styles/iframe.css';

  import Component0 from '../../A:\dev\project\React\Hoko\src\components\analytics\AnalyticsNavbar.jsx';
reactComponents['AnalyticsNavbar'] = Component0;

其他一些有用的代码：我的组件为：AnalyticsNavbar.jsx

/**
 * Created by Abbas on 16/04/2019.
 */
import '../../res/css/analytics/analytics_navbar.css';
import * as PropTypes from 'prop-types';
import Link from 'react-router-dom/es/Link';
import React from 'react';

/**
 * This component renders nav bar for analytics page.
 * @component
 * @example
 * const analyticsType = 'usage_details'
 * return (
 *   <AnalyticsNavbar analyticsType={analyticsType} />
 * )
 */
function AnalyticsNavbar (props) {

  return (
    <div className='analytics-navbar'>
      <div className='hoko-body'>
        <div className={'navbar-item ' + (props.analyticsType === 'usage_details' ? 'selected' : '')}>
          <Link to='./usage-details'>
            <div className='icon'>
              <i className='fas fa-user-clock' />
            </div>
            {'میزان استفاده'}
          </Link>
        </div>
        <div className='navbar-item'>
          <Link to='./trouble-spots'>
            <div className='icon'>
              <img src={require('../../res/image/analytics/trouble_spots.png')} />
            </div>
            {'نقاط ضعف'}
          </Link>
        </div>
        <div className='navbar-item'>
          <Link to='./trouble-spots'>
            <div className='icon'>
              <img src={require('../../res/image/analytics/scores.png')} />
            </div>
            {'امتیازات'}
          </Link>
        </div>
        <div className='navbar-item'>
          <Link to='./trouble-spots'>
            <div className='icon'>
              <img src={require('../../res/image/analytics/questions.png')} />
            </div>
            {'سوالات'}
          </Link>
        </div>
      </div>
    </div>
  )
}

AnalyticsNavbar.propTypes = {
  analyticsType: PropTypes.string.isRequired
};

export default AnalyticsNavbar;

jsDoc 的配置文件为 jsdoc.conf.json:

{
  "tags": {
    "allowUnknownTags": true
  },
  "source": {
    "include": ["./src"]
  },
  "plugins": [
    "plugins/markdown",
    "better-docs/component"
  ],
  "opts": {
    "encoding": "utf8",
    "destination": "docs/",
    "recurse": true,
    "verbose": true,
    "template": "./node_modules/better-docs"
  },
  "templates": {
    "better-docs": {
      "name": "My React components"
    }
  }
}

package.json

中的脚本部分

"scripts

    ": {
        "start": "node scripts/start.js",
        "build": "node scripts/build.js",
        "test": "node scripts/test.js",
        "docs": "jsdoc -c ./jsdoc.conf.json"
      },

我该如何解决？非常感谢。

Answer 1

我遇到了类似的问题。基本上，问题是路径模块在 Windows 的路径中放置了“\”而不是“/”，这会导致路径中断。

文件 entry.js 是由 bundler.js 创建的，可以在 node_modules/better-docs/bundler.js 中找到。这是在 entry.js 中放置错误路径的文件。为了解决这个问题，我通过在创建路径时添加 .replace(/\/g,"/")，在 bundler.js 文件的多个位置手动将“\”替换为“/”。

我如何更改 bundler.js 文件（只需查找所有 .replace(/\/g,"/") 以查看您需要添加它们的位置）：

const fs = require('fs')
const path = require('path').posix
const execSync = require('child_process').execSync

const VUE_WRAPPER = process.env.IS_DEV ? 'src/vue-wrapper.js' : 'lib/vue-wrapper.js'
const REACT_WRAPPER = process.env.IS_DEV ? 'src/react-wrapper.jsx' : 'lib/react-wrapper.js'

module.exports = function bundle (Components, out, config) {
  if (!Components.length) {
    return
  }
  const vueComponents = Components.filter(c => c.component.type === 'vue')
  const reactComponents = Components.filter(c => c.component.type === 'react')
  const entry = path.join(out.replace(/\/g, "/"), 'entry.js').replace(/\/g, "/")
  const absoluteOut = path.resolve(out).replace(/\/g,"/")

  let init = `
    window.reactComponents = {};\n
    window.vueComponents = {};\n
  `
  if (vueComponents.length) {
    init = init + `
      import Vue from 'vue/dist/vue.js';\n
      window.Vue = Vue;\n

      import VueWrapper from '${path.relative(absoluteOut, path.join(__dirname, VUE_WRAPPER).replace(/\/g, "/"))}';\n
      window.VueWrapper = VueWrapper;\n
    `
  }
  if (reactComponents.length) {
    init = init + `
      import React from "react";\n
      import ReactDOM from "react-dom";\n

      import ReactWrapper from '${path.relative(absoluteOut, path.join(__dirname, REACT_WRAPPER).replace(/\/g, "/"))}';\n

      window.React = React;\n
      window.ReactDOM = ReactDOM;\n
      window.ReactWrapper = ReactWrapper;\n
    `
  }

  // Import css
  init = init + `
    import './styles/reset.css';\n
    import './styles/iframe.css';\n
  `

  if (config.betterDocs.component) {
    if(config.betterDocs.component.wrapper) {
      const absolute = path.resolve(config.betterDocs.component.wrapper)
      init +=`
      import _CustomWrapper from '${path.relative(absoluteOut, absolute)}';\n
      window._CustomWrapper = _CustomWrapper;\n
      `
    }
    if(config.betterDocs.component.entry
      && config.betterDocs.component.entry.length) {
      init = `${config.betterDocs.component.entry.join('\n')}\n${init}`
    }
  }

  const entryFile = init + Components.map((c, i) => {
    const { displayName, filePath, type } = c.component
    const relativePath = path.relative(absoluteOut, filePath.replace(/\/g, "/"))
    const name = `Component${i}`
    return [
      `import ${name} from '${relativePath}';`,
      `${type}Components['${displayName}'] = ${name};`,
    ].join('\n')
  }).join('\n\n')

  console.log('Generating entry file for "components" plugin')
  fs.writeFileSync(entry, entryFile)
  console.log('Bundling components')
  const outDist = path.join(out.replace(/\/g, "/"), 'build').replace(/\/g, "/")
  const cmd = `parcel build ${entry} --out-dir ${outDist}`
  console.log(`running: ${cmd}`)
  try {
    execSync(cmd)
  } catch (error) {
    if(error.output && error.output.length){
      console.log(error.output[1].toString())
    }
    throw error
  }
}

better-docs 错误地创建了 entry.js 文件

better-docs creates entry.js file incorrectly

javascript

documentation

jsdoc

reactjs