better-docs creates entry.js file incorrectly

Question

I tried to use better-docs plugin for jsDoc to make documentation for my react.js project through this link: https://medium.com/@wojciechkrysiak/document-reactjs-components-with-preview-by-using-jsdoc-70d39d2cc777.

When i run bellow command to create my docs:

npm run docs

I get this error:

×  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)

As is visible in top error, problem comes from bad addressing for my components:

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

There isn't any '/' character!

I founded this bad addressing exists also in entry.js file in docs folder. used '\' instead of '/'.

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;

some other codes that can be useful: my component as : 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;

Config file for jsDoc as 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"
    }
  }
}

scripts section in package.json

"scripts

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

How can i fix it? Thanks a lot.

Answer 1

I had a similar issue. Basically, the problem is that the path module puts "\" in paths for Windows instead of "/" which causes paths to break.

The file entry.js is created by bundler.js which can be found in node_modules/better-docs/bundler.js This is the file that puts the wrong paths in entry.js. To fix this, I manually replaced the "\" with "/" in multiple places in the bundler.js file by adding .replace(/\\/g,"/") when paths are created.

How I changed the bundler.js file (just look for all the .replace(/\\/g,"/") to see where you need to add them):

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
  }
}