Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

@const description causes docma not to render an api page #45

Closed
dkebler opened this issue Aug 2, 2018 · 5 comments
Closed

@const description causes docma not to render an api page #45

dkebler opened this issue Aug 2, 2018 · 5 comments
Labels
duplicate v3 ✓ Fixed or implemented. To be released.

Comments

@dkebler
Copy link

dkebler commented Aug 2, 2018 •
edited
Loading

I understand correctly the first entry in the src: key array will be used for the ?api= query route??

So docma is parsing my source files (because if I put in a syntax error it catches it) but then there is no actual html being rendered at the api route. It doesn't show a 404 just a blank page so it thinks the route is good just nothing there. Nothing obvious in the build directory either. Is there supposed to be an api subdirectory cause there isn't. (there is a content subdirectory)

http://localhost:9000/?api=UCI

btw the guide page markdown renders fine at the web root.

my config file

  // docma build configuration file for UCI
module.exports = {
  src: [
    {
      UCI: [
        '../uci-socket/src/*.js' 
      ],
    },
    {
       guide: '../uci-docs-guide/README.md'
    }
  ],
  dest: './docs',
  app: {
    title: 'UCI Documentation',
    routing: 'query',
    entrance: 'content:guide',
    base: '/'
  },
  template: {
    path: 'zebra',
    options: {
      title: {
        label: 'documentation',
        href: '/?'
      },
      navbar: true,
      sidebar: {
        enabled: true,
        outline: 'tree'
      }
    }
  }
}

not using the cli but running this

import Docma from 'docma'
import config from './config'

const docma = new Docma()
docma.build(config)
  .then(success => {
    console.log('Documentation is built successfully.', success)
  })
  .catch(error => {
    console.log(error.stack)
  })
@dkebler
Copy link
Author

dkebler commented Aug 2, 2018 •
edited
Loading

ok I now understand that the rendered api docs are in the docma-web.js file and I can search and find the functions from my source. Why is that not getting rendered to the page.

the source of the "blank" page is

<!DOCTYPE html>
<html>
<head>
    <title>UCI Documentation</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta charset="utf-8">
    <meta name="generator" content="Docma - https://onury.io/docma">

    <link rel="stylesheet" type="text/css" href="css/docma.css">
    <link rel="stylesheet" type="text/css" href="css/styles.css">

    <script src="js/docma-web.js"></script>
    <script src="//code.jquery.com/jquery-3.3.1.min.js" crossorigin="anonymous"></script>
    <script src="js/highlight.pack.js"></script>
    <script src="js/tippy.all.min.js"></script>
    <script defer="" src="//use.fontawesome.com/releases/v5.0.9/js/all.js"></script>
    <script src="js/app.min.js"></script>
</head>

<body>
    <div id="docma-main"></div>



</body>
</html>

and if I click on the js/docma-web.js link it comes up and indeed reference to my source functions are there. Yet a blank page is rendering???

@dkebler
Copy link
Author

dkebler commented Aug 7, 2018

with debug on it all looks fine.

Building documentation...

Docma Version:  2.1.0
Using Template: docma-template-zebra (version: 2.1.0)

Running template pre-build process...

Expanding source files...
Expanding: ../uci-socket/src/*.js into "UCI"
Expanding: ../uci-docs-guide/README.md into "guide"
Parsing 4 Javascript file(s)...
Copying template files/directories...
Writing SPA main file...
Parsing 1 Markdown file(s)...
Processing 0 HTML file(s)...
No assets to be copied over...
Compiling Docma (Web) Core...
Compiling SPA partials...
Writing docma-web.js...
Evaluating server/host configuration for the SPA...
Running template post-build process...

Documentation is built successfully...

Configured SPA Routes:

type     name   path             contentPath         sourceType
-------  -----  ---------------  ------------------  ----------
api      _def_  /?api            —                   js
api      UCI    /?api=UCI        —                   js
content  guide  /?content=guide  content/guide.html  md

Before you publish your docs, note that minification is turned off and web-logs is enabled.
Documentation is built successfully. true
Done in 1.70s.

When loading ?api=UCI
in firefox console shows a type error, the error below.

TypeError: kind is undefined[Learn More]
app.min.js:17:2985
helper.getSymbolInfo
http://127.0.0.1:8080/js/app.min.js:17:2985
getSymbolData
http://127.0.0.1:8080/js/app.min.js:17:5743
getSidebarNavItem
http://127.0.0.1:8080/js/app.min.js:17:7692
helper.buildSidebarNodes/<
http://127.0.0.1:8080/js/app.min.js:17:8673
forEach self-hosted:261:13 helper.buildSidebarNodes
http://127.0.0.1:8080/js/app.min.js:17:8454
helper.buildSidebarNodes/<
http://127.0.0.1:8080/js/app.min.js:17:8907
forEach self-hosted:261:13 helper.buildSidebarNodes
http://127.0.0.1:8080/js/app.min.js:17:8454
<anonymous>
http://127.0.0.1:8080/js/app.min.js:17:16595
dust.filter
http://127.0.0.1:8080/js/docma-web.js:285:20
Chunk.prototype.reference
http://127.0.0.1:8080/js/docma-web.js:767:25
body_0
http://127.0.0.1:8080/js/docma-web.js:3261:81
load
http://127.0.0.1:8080/js/docma-web.js:154:14
Chunk.prototype.partial
http://127.0.0.1:8080/js/docma-web.js:914:14
body_1
http://127.0.0.1:8080/js/docma-web.js:3254:570
Chunk.prototype.exists
http://127.0.0.1:8080/js/docma-web.js:856:16
body_0
http://127.0.0.1:8080/js/docma-web.js:3254:83
load
http://127.0.0.1:8080/js/docma-web.js:154:14
dust.render
http://127.0.0.1:8080/js/docma-web.js:100:7
DocmaWeb.prototype._render
http://127.0.0.1:8080/js/docma-web.js:5963:5
DocmaWeb.prototype.render
http://127.0.0.1:8080/js/docma-web.js:6057:9
DocmaWeb.Route.prototype.apply
http://127.0.0.1:8080/js/docma-web.js:6309:5
<anonymous>

@dkebler
Copy link
Author

dkebler commented Aug 7, 2018 •
edited
Loading

Looks like it was the source code jsdoc. I have tracked it down. Docma does not like this @const JSDOC line with the descriptive text after.

/** @const {String} DEFAULT_SOCKET_NAME sets a default socket name */
const DEFAULT_SOCKET_NAME = 'uci-sock'

with console error

docma-web.js:5964 Uncaught TypeError: Cannot read property 'replace' of undefined
    at Object.helper.getSymbolInfo (app.min.js:17)
    at getSymbolData (app.min.js:17)
    at getSidebarNavItem (app.min.js:17)
    at app.min.js:17
    at Array.forEach (<anonymous>)
    at Object.helper.buildSidebarNodes (app.min.js:17)
    at app.min.js:17
    at Array.forEach (<anonymous>)
    at Object.helper.buildSidebarNodes (app.min.js:17)
    at app.min.js:17
docma-web.js:5964 Uncaught TypeError: Cannot read property 'replace' of undefined
    at Object.helper.getSymbolInfo (app.min.js:17)
    at getSymbolData (app.min.js:17)
    at getSidebarNavItem (app.min.js:17)
    at app.min.js:17
    at Array.forEach (<anonymous>)
    at Object.helper.buildSidebarNodes (app.min.js:17)
    at app.min.js:17
    at Array.forEach (<anonymous>)
    at Object.helper.buildSidebarNodes (app.min.js:17)
    at app.min.js:17docma-web.js:5964 Uncaught TypeError: Cannot read property 'replace' of undefined
    at Object.helper.getSymbolInfo (app.min.js:17)
    at getSymbolData (app.min.js:17)
    at getSidebarNavItem (app.min.js:17)
    at app.min.js:17
    at Array.forEach (<anonymous>)
    at Object.helper.buildSidebarNodes (app.min.js:17)
    at app.min.js:17
    at Array.forEach (<anonymous>)
    at Object.helper.buildSidebarNodes (app.min.js:17)
    at app.min.js:17

if I remove it the error is gone and the page renders

/** @const {String} DEFAULT_SOCKET_NAME */
const DEFAULT_SOCKET_NAME = 'uci-sock'

as far as I know there is nothing wrong with adding a description to an @const tag

@dkebler dkebler changed the title nothing rendering at api route for a set of js sources @const description causes docma not to render an api page Aug 7, 2018
@MaienM
Copy link
Contributor

MaienM commented Aug 14, 2018

This is a duplicate of #41, which has a workaround you could use in the meantime.

@onury onury added ✓ Fixed or implemented. To be released. duplicate v3 labels Nov 13, 2018
@onury
Copy link
Owner

onury commented Nov 18, 2018

Fixed with Docma v3.0.0.

@onury onury closed this as completed Nov 18, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
duplicate v3 ✓ Fixed or implemented. To be released.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@MaienM @dkebler @onury