onury / docma Goto Github PK

View Code? Open in Web Editor NEW

330.0 6.0 34.0 17.4 MB

A powerful tool to easily generate beautiful HTML documentation from JavaScript (JSDoc), Markdown and HTML files.

Home Page: https://onury.io/docma

License: MIT License

JavaScript 83.01% CSS 13.37% HTML 3.62%

api reference documentation markdown jsdoc javascript docs

docma's People

Contributors

Stargazers

Watchers

docma's Issues

How to omit constructor?

We are writing AngularJS services, which are classes, and therefore, we don't need to document the constructor, but whatever I do, I can't get then to be not included. @ignore doesn't work for them. Is there a way or setting that I can not include the constructor, but keep the class api doc?

Relative Links in Markdown

Hey guys, wanted to thank you for this great project. Still waiting for ES6 support but otherwise its working nicely. I have one issue though related to relative links inside the README.md

example

I have a README.md file in the project root that contains the following lines

- [Login](doc/login.md)
- [Logout](doc/logout.md)

When the doc is generated.. the console spits out the following

content  login       /login           content/login.html
content  logout      /logout          content/logout.html

However, the content index.html still contains the doc/login.md.. it doesn't link to the new generated html files.

And because of the base path.. being different between between the actual code and the documentation path.. the relative path doesn't resolve.

Any insights?

Should the Markdown files point to the generated files instead of Markdown files ?

Help with setup

This looks like a cool and easy way to document, but i can not figure out how to set it up. If you have time, can you help me setup an example project or just the basics on getting started?

@deprecated tag should be considered

In the default template, symbols with @deprecated tag should either be faded or have a warning shown. This could be configurable.

Uncaught TypeError: Converting circular structure to JSON

When I load my documentation website at https://maxrumsey/hookcord I receive this error message: Uncaught TypeError: Converting circular structure to JSON
The full error is:

Uncaught TypeError: Converting circular structure to JSON
    at JSON.stringify (<anonymous>)
    at docma-web.js:26
    at Stub.callback (docma-web.js:26)
    at Stub.flush (docma-web.js:1)
    at Chunk.setError (docma-web.js:1)
    at Object.dust.render (docma-web.js:1)
    at DocmaWeb._render (docma-web.js:26)
    at DocmaWeb._render404 (docma-web.js:26)
    at DocmaWeb.render (docma-web.js:26)
    at DocmaWeb.Route.apply (docma-web.js:28)
    at docma-web.js:37
    at docma-web.js:3
    at o (docma-web.js:3)
    at docma-web.js:3
    at o (docma-web.js:3)
    at docma-web.js:3
    at o (docma-web.js:3)
    at Function.L.dispatch (docma-web.js:3)
    at Function.L.replace (docma-web.js:3)
    at Function.L.start (docma-web.js:3)
    at window.onload (docma-web.js:37)

My repository is: https://github.com/maxrumsey/hookcord/
This is what I see when I load maxrumsey.xyz/hookcord/

Steps to reproduce:

Fork Repo Above and set it to run with Github Pages

inheritdoc not respecting "smart linking"

given

// ./lib/a.js
/**
 * A base class
 * @memberof myModule
 */
class A {}

// ./lib/b.js
import A from './a'
/**
 * A child class
 * @memberof myModule
 * @extends myModule~A
 * @inheritdoc
 */
class B extends A {}

// index.js
/** 
 * A module that does stuff
 * @module myModule 
*/
import B from './lib/b'
export default {B}

both the inheritance of properties and the "Extends" link properly generate for B but when you do:

// ./lib/b.js
import A from './a'
/**
 * A child class
 * @memberof myModule
 * @extends A
 * @inheritdoc
 */
class B extends A {}

the inheritance breaks (i.e. none of the class properties are carried over) however the "Extends" link still points to the proper base class.

Suggestion: option to collapse all methods on the side-bar

Let's say I have two classes displayed on the left sidebar:

MyClass
MyClass#method1
MyClass#method2
MyClass2
MyClass2#method1
MyClass2#method2
...

It would be great if there was a way to should only root level initially:

MyClass
MyClass2

Clicking on MyClass would then expand MyClass and show its methods/properties:

MyClass
MyClass#method1
MyClass#method2
MyClass2

As it is now, the list becomes quickly huge once you have several classes that have lots of methods.

Example:

Add an option for toggling line numbers within template

Missing documentation

I found that the following methods were not documented:

docma.utils.listType
docma.utils.listTypeDesc

Since there are used in the default template's filters ($returns, $extends, $exceptions) I think it would be a good idea to add them.

Version 1.5.1 creating broken documentation?

It probably is me, since I just started trying to use docma.

But when I use Chrome to load the documetation, I get a page not found error (404). (even though it should all be at http://localhost/WebView/docs/ )

docma-web.js:38 Uncaught Error: Page or content not found for route: {}
    at docma-web.js:38
    at Stub.callback (docma-web.js:38)
    at Stub.flush (docma-web.js:4)
    at Chunk.setError (docma-web.js:4)
    at Object.dust.render (docma-web.js:4)
    at n (docma-web.js:38)
    at r (docma-web.js:38)
    at Object.docma.render (docma-web.js:38)
    at e.apply (docma-web.js:38)
    at docma-web.js:38
(anonymous) @ docma-web.js:38
(anonymous) @ docma-web.js:38
Stub.flush @ docma-web.js:4
Chunk.setError @ docma-web.js:4
dust.render @ docma-web.js:4
n @ docma-web.js:38
r @ docma-web.js:38
docma.render @ docma-web.js:38
e.apply @ docma-web.js:38
(anonymous) @ docma-web.js:38
(anonymous) @ docma-web.js:9
n @ docma-web.js:9
(anonymous) @ docma-web.js:9
n @ docma-web.js:9
(anonymous) @ docma-web.js:9
n @ docma-web.js:9
r.dispatch @ docma-web.js:9
r.replace @ docma-web.js:9
r.start @ docma-web.js:9
window.onload @ docma-web.js:38

The build seemed to go fine:

docma -c ./docma.json -d ./docs -s ./scripts/*



Building documentation...

Using Template: Docma Default Template (version: 1.7.0)

Expanding source files...
Expanding: scripts\*
 » Unsupported file ignored: D:\wwwroot\WebView\scripts\Config.json
Parsing 8 Javascript file(s)...
Copying template files/directories...
Compiling SPA styles...
(node:11044) Warning: a promise was created in a handler at fs.js:149:15 but was not returned from it, see http://goo.gl/rRqMUw
    at Object.ret [as readFileAsync] (eval at makeNodePromisifiedEval (D:\wwwroot\WebView\node_modules\bluebird\js\release\promisify.js:184:12), <anonymous>:8:21)
Compiling SPA scripts...
Writing SPA main file...
Parsing 0 Markdown file(s)...
Processing 0 HTML file(s)...
Compiling Docma (Web) Core...
Compiling SPA partials...
Writing docma-web.js ...

Documentation is built successfully...

Configured SPA Routes:

type  name   path   contentPath
----  -----  -----  -----------
api   _def_  /?api  null

The template is as follows (all the js files are at ./scripts/*.js and the webpage is at webview.html

{
    "name": "WebView Documentation",
    "author": "Draper Laboratory",
    "version": "1.7.0",
    "license": "Private",
    "main": "webview.html",
    "options": {
        "title": "WebView Documetation",
        "sidebar": true,
        "collapsed": false,
        "outline": "tree", 
        "badges": true,
        "symbolMeta": false,
        "search": true,
        "navbar": true,
        "navItems": []
    },
    "compile": {

    },
    "ignore": [
        "libs/**",
        "node_modules/**",
        "*.md",
        "LICENSE"
    ]
}

Sort properties first/last

Right now, properties and methods are mixed, so a class description could look like this when sorted:

Class
Class.aMethod
Class.bMethod
Class.cProperty
Class.dMethod
Class.eProperty

It would be great if there was an option to sort first (or last) methods and then properties, so the class description would look like this:

Class
Class.aMethod
Class.bMethod
Class.dMethod
Class.cProperty
Class.eProperty

or (properties first):

Class
Class.cProperty
Class.eProperty
Class.aMethod
Class.bMethod
Class.dMethod

I am planning to add the option to the template I am working on but am not sure how to do it: I guess I could do that in the route event?

Suggestion: do not remove .git when building documentation

When building the documentation, docma will empty the directory specified with the -d option.

Right now, I am generating the documentation at the root of a git repository, so that when I want to update the documentation, I just have to commit/push the new files to my repository to update the website.

But since docma empties the whole directory, it also removes the .git directory so I can't commit/push anymore.

Suggestion: allow to keep hidden files/directories (ie: starting with a dot). Or maybe a new option could allow to specify a list of files/patterns to keep?

Uncaught TypeError: Cannot read property 'split' of null

Hello, I've created doc files with sample js file. There is an error in browser console.(index.html)

Error:

docma-web.js:38 Uncaught TypeError: Cannot read property 'split' of null at Function.t.fromID (docma-web.js:38) at window.onload (docma-web.js:38)

Won't create

I've tried to generate a Documentation.

Tested on my empty JS-Function:

/**
	@class GameSocket
*/
var GameSocket = (new function GameSocket() {

}());

But noting will generated. Can't find informations about the Comments-Syntax. On YUIDoc this will works, but i want to search alternatives.

Without error, API documentation not rendering

Locally using the docma provided server, everything loads properly except for the API. The left panel opens and looks like it should, but the list of documented items is missing. I can see the definition of what is supposed to be rendering in the left panel described in docma-web.js. I can see no error in the debug output when generating the SPA and I can see no error when the SPA attempts to load the API documentation. To add to the potential confusion, I have not altered the code for quite some time and I have verified this with diffing between the time when the API was rendering properly and now when it is not. I have been messing with the routing in order to get the SPA to operate properly locally as well as in GitHub pages. So, there was a time, albeit short time, when the API documentation rendered properly and now it no longer does.

{
  "src": ["*.md", {"api":["./src/*.js"]}],
  "dest": "./docs",
  "clean": true,
  "debug": true,
  "jsdoc": {
    "undescribed": true
  },
  "app": {
    "title": "Data Access Library",
    "server": "github",
    "entrance": "content:readme",
    "routing": "path",
    "base": ""
  },
  "template": { ... }
}

Here is the documentation generation output:

myuser:myrepo myuser$ yarn document
yarn run v1.10.1
$ docma && docma serve ./docs

Using configuration file: /Users/myuser/code/myrepo/docma.json

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: *.md 
 » Queued: /Users/myuser/code/myrepo/changelog.md
 » Queued: /Users/myuser/code/myrepo/developing.md
 » Queued: /Users/myuser/code/myrepo/readme.md
Expanding: ./src/*.js into "api"
 » Queued: /Users/myuser/code/myrepo/src/dataAccessLibrary.js
 » Queued: /Users/myuser/code/myrepo/src/index.js
 » Queued: /Users/myuser/code/myrepo/src/onlineAPI.js
 » Queued: /Users/myuser/code/myrepo/src/utilities.js
Parsing 4 Javascript file(s)...
 » Parsing (_def_): 0 files
 » Parsing (api): 4 files
Copying template files/directories...
 » Creating directory: /Users/myuser/code/myrepo/docs/css
 » Copying: template/css/styles.css
 » Creating directory: /Users/myuser/code/myrepo/docs/img
 » Copying: template/img/tree-deep.png
 » Copying: template/img/tree-first.png
 » Copying: template/img/tree-folded.png
 » Copying: template/img/tree-last.png
 » Copying: template/img/tree-node.png
 » Copying: template/img/tree-parent.png
 » Copying: template/img/tree-space.png
 » Creating directory: /Users/myuser/code/myrepo/docs/js
 » Copying: template/js/app.min.js
 » Copying: template/js/highlight.pack.js
 » Copying: template/js/tippy.all.min.js
 » Compiling: docma.less
 » Writing: /Users/myuser/code/myrepo/docs/css/docma.css
Writing SPA main file...
 » Creating: /Users/myuser/code/myrepo/docs/index.html
Parsing 3 Markdown file(s)...
 » Parsing (changelog): /Users/myuser/code/myrepo/changelog.md
 » Parsing (developing): /Users/myuser/code/myrepo/developing.md
 » Parsing (readme): /Users/myuser/code/myrepo/readme.md
Processing 0 HTML file(s)...
Copying assets...
 » Copying: /Users/myuser/code/myrepo/.assets/favicon.ico » /Users/myuser/code/myrepo/docs/img/favicon.ico
 » Copying: /Users/myuser/code/myrepo/.assets/logo-Social-1200.png » /Users/myuser/code/myrepo/docs/img/logo-Social-1200.png
 » Copying: /Users/myuser/code/myrepo/.assets/logo.png » /Users/myuser/code/myrepo/docs/img/logo.png
Compiling Docma (Web) Core...
 » Compiling: components/dust-core.js
 » Compiling: components/dust-helpers.js
 » Compiling: components/page.js
 » Compiling: components/EventEmitter.js
Compiling SPA partials...
 » Compiling: template/partials/docma-404.html
 » Compiling: template/partials/docma-api.html
 » Compiling: template/partials/docma-content.html
 » Compiling: template/partials/widgets/enums.html
 » Compiling: template/partials/widgets/navbar.html
 » Compiling: template/partials/widgets/navitem.html
 » Compiling: template/partials/widgets/params.html
 » Compiling: template/partials/widgets/properties.html
 » Compiling: template/partials/widgets/sidebar.html
 » Compiling: template/partials/widgets/symbol.html
Writing docma-web.js...
 » Done.
Evaluating server/host configuration for the SPA...
Generating indexed directories for GitHub...
Running template post-build process...

Documentation is built successfully...
 » Script Size:  254.6 KB (unminifed, fully documented), 54.1 KB (gzipped)
 » Total Routes: 5 (2 API, 3 content)

Configured SPA Routes: 

type     name        path         contentPath              sourceType
-------  ----------  -----------  -----------------------  ----------
api      _def_       /api         —                        js        
api      api         /api/api     —                        js        
content  changelog   /changelog   content/changelog.html   md        
content  developing  /developing  content/developing.html  md        
content  readme      /readme      content/readme.html      md        

Before you publish your docs, note that minification is turned off and web-logs is enabled.
 » Use the 'debug' option in your build configuration to change this.


Starting server @ path: /Users/myuser/code/myrepo/docs
Serving SPA @ http://localhost:9000/

Allow preview from local file URL

Currently, the SPA can't be previewed via a local file URL. It always shows a 404 page.

I did manage to hack docma-web.js to enable hashbang routing, which allowed me to view an API via:

file:///path/to/output/index.html#!/?api=group

However, none of the links worked and it was pretty fragile in general.

Would it be possible to support previewing via a local file URL? This is the ideal mode for development, IMO.

Support @example <caption> style of jsdoc

Hi, I 'm a docma template user and it's amazing beautiful, but i see the docma do not support the <caption> style of @example, the api-doc is:

http://usejsdoc.org/tags-example.html

Docma only creates README/guide

Hey, I'm trying to use Docma for my own CMS based on Node.js, but running Docma only generates a page for my README.md (so the guide). I started writing a script (docma.js) in my project's root with the following content:

"use strict";

const Docma = require("docma");

const buildConfig = {
	src: [
		{
			core: './index.js'
		},
		'./LICENSE.md',
		{
			guide: './README.md'
		}
	],
	dest: './output/docs',
	app: {
		title: 'WebSuite Documentation',
		routing: 'path',
		entrance: 'content:guide',
		base: '/docs'
	},
	template: {
		path: 'zebra',
		options: {
			title: {
				label: 'WebSuite Documentation',
				href: '/docs/?'
			},
			navbar: true,
			sidebar: {
				enabled: true,
				outline: 'tree',
				collapsed: true,
				toolbar: true
			}
		}
	},
	clean: "true"
};

Docma.create()
	.build(buildConfig)
	.catch(error => {
		console.log(error);
	});

Currently the app-entrance is the guide. When now visiting the docs I see my README.md. But changing now the app-entrance to my 'core', that currently has only one file to test it, then I get a 404-Error visiting my docs.

Following you'll find a screenshot from IntelliJ from the output-folder:

Did I do any mistakes writing my config? Thanks for helping me :)

Greetings from Germany
ilou

left fly-out list has no scroll-bar in Firefox

In tasktimer docma while viewing in the latest firefox (50.0.2 on linux) there is no scroll to get to the last items. Works fine the chrome.

Also curious why addTask is considered public by jsdoc but it doesn't appear in built site?
Just never built? or does docma allow exclusion of certain elements in the builder file?

Well, might as well start putting in my jsdoc stuff. I'll give a run later.

Tasktimer looks like a good example to refer to.. thx

@enum doesn't produce the possible values in the generate docs

I can't seem to figure out how to have the actual possible values in the generated docs. I tried addng /** @member {string} */ to the values, but that also doesn't work. I use @readonly @enum {string} on the object.

How to include assets to generated documentation?

I have some images in one of the .md I'm using in my Docma documentation:

![test](img/foo.png)

That's get transformed as:

<img src="img/foo.png" alt="test" />

But the img/foo.png is not copied to the output folder so when reading the documentation I don't see the image.

Is there a way to specify an assets directory that will be added to the generated documentation? Or should I do it by hand?

Hierarchy/Outline displays incorrectly

Problem

Code organized by namespace is not sorted or grouped correctly.

Image Examples:

(Not working, oddly) Correct level of nesting, but not grouped under correct namespace:

(Working) Some tools are correctly grouped under the namespace:

Code Snippet Examples:

Grouped Correctly
Example configuration for pictured LengthTool:

/**
 * @public
 * @class LengthTool
 * @memberof Tools.Annotation
 *
 * @classdesc Tool for measuring distances.
 * @extends BaseAnnotationTool
 */
export default class LengthTool extends BaseAnnotationTool {
...
}

Not Grouped Correctly
Example configuration for pictured AngleTool:

/**
 * @public
 * @class AngleTool
 * @memberof Tools.Annotation
 *
 * @classdesc Create and position an angle by placing three consecutive points.
 * @extends BaseAnnotationTool
 */
export default class AngleTool extends BaseAnnotationTool {
...
}

support {@link }

Looks like docma doesn't support the jsdoc {@link}. Doesn't throw an error but no link is displayed.

This would be very useful to say link to an anchor in a guide or to the source code itself

http://usejsdoc.org/tags-inline-link.html

Support extensionless files

currently there is no way to compile an extension less text document:

// docma.json
{
  "src": [
    "./src/**/*.js",
    "./README.md",
    "./CHANGELOG.md",
    "./LICENSE"
  ]
}

will produce the following warning and fail to compile the file:

Unsupported file ignored: /$HOME/my-project/LICENSE

please add support for extension less text files as this format for LICENSE is fairly common practice (its the default new repo behavior on github)

$ is not a function

command line docma -c docma.json there is a error:

$ is not a function

Using README as title page?

Is there a way to use the readme as the initial page? Maybe I'm just missing it in the docs...

this is what I have, which executes jsdoc well, but doesn't have the title page (like your docs :))

    return Docma.create()
      .build({
        src: [
          './index.js',
          './README.md'
        ],
        dest: './docs'
      });

Package published on npm has broken command line

When I try running the docma command, it immediately crashes with Cannot find module '../lib/docma'. Upon further investigation, this is because, in the published version, the file is named ../lib/Docma.js. Since Unix systems are case-sensitive, the file is not found. This seems to be more of an issue with the way you packaged Docma than with the actual code itself. It looks like the file is named correctly in the repo at the tag you specified.

best way for dev auto build

Doesn't look like the cli has an watch/rebuild mode (new feature?). So was just going to use the api to do a build and then run that with nodemon watching my source directories to get an auto rebuild. Do you suggest another (better) way? I can run a web server separately.

@emits not documented?

/**
* Test Class
* @emits myEvent - Desc
*/
class Test extends EventEmitter {

}

The @emits attrib is not in the generated api doc.

@const description causes docma not to render an api page

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

TypeError: (name || "").replace is not a function

I'm able to generate documentation if I limit it to a small subset of my source. When I expand it to all files, I get this error. No new output is generated. I'm unable to identify where/what is throwing this error.

Any/all help is appreciated; even if it's just some advice on how to debug docma 👍

@link by namepath

According to the docs of @link, it should be possible to create link using the namepath. However, when I do so in docma, this creates an incorrect link. Looking at the code, there are some commented out blocks that seem to relate to this, but these appear to be unfinished (if (symbolNames && symbolNames.indexOf(link) >= 0) {..} in Utils.parseLinks in DocmaWeb.Utils.js).

I can work around this by manually prefixing the namepath with #, as the namepaths seem to be anchors, but it would be nice to have proper support for this.

Declaring const will cause docma to fail to render SPA without console warn

It would appear that attempting to document a variable declared with const will cause docma to render an empty white page without any output to the terminal as to what the cause may be:

to reproduce simply document a file like this:

/**
  * A module that does things 
  * @module myModule 
  **/

 /** A variable declared with const */
const foo = 'foo'

and then run docma -s src/**/*.js -d docs && docma serve docs

The server will render the navbar but displays an empty white page for the ?api route.

terminal says nothing:

Using configuration file: $HOME/my-project/docma.json

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: ./src/**/*.js
Expanding: ./README.md
Expanding: ./CHANGELOG.md
Parsing 8 Javascript file(s)...
Copying template files/directories...
Writing SPA main file...
Parsing 2 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
content  readme     /?content=readme     content/readme.html     md
content  changelog  /?content=changelog  content/changelog.html  md


> [email protected] doc:serve $HOME/my-project/
> docma serve docs


Starting server @ path: $HOME/my-project/docs
Serving SPA @ http://localhost:9000/

config:

{
  "src": [
    "./src/**/*.js",
    "./README.md",
    "./CHANGELOG.md"
  ],
  "dest": "./docs",
}

Same configuration does not work both locally and in GitHub pages

I can navigate the SPA locally or in the remote GitHub pages. But, I cannot get the configuration right so I can navigate in both with the same configuration.

If I have the base set like so:
"base":"/myrepo" then the navigation works in GitHub pages but not locally.
If I have the base set like:
"base":"/" or "base":"" then the navigation works locally but not in GitHub pages.

I think it is safe to assume that the paths of the SPA navigation are not relative to the directory from which the SPA originates and are instead based on the <base> tag.

I suggest that if no base configuration exists or it is set to an empty string that the generated paths be relative to the path from which the SPA originates.

If there is a way to configure the app so that a user can navigate the app both locally and in GitHub pages, I would love to hear about it.

Return type parameters should be escaped in template

Symbols with type parameters (such as Promise<Array>) are parsed incorrectly. This causes unclosed tags within a <code></code> block which breaks the template HTML.

Base path is not auto-set to "/" (default) causes ENOENT: no such file or directory

given the following configuration:

{
  "src": [
      {
        "my-lib": [
          "./src/**",
          "!./src/errors/**"
        ]
      },
      "./CHANGELOG.md",
      "./CODE_OF_CONDUCT.md",
      "./CONTRIBUTING.md",
      "./docs/**/*.md"
    ],
  "dest": "./.docma",
  "app": {
    "title": "MyLib",
    "entrance": "content:readme",
    "server": "github",
    "routing": "path"
  }
}

images in the left navigation begin to break and terminal errors are logged:

Error: ENOENT: no such file or directory, stat '$MY_PROJECT/.docma/api/img/tree-parent.png'
Error: ENOENT: no such file or directory, stat '$MY_PROJECT/.docma/api/img//tree-folded.png'
Error: ENOENT: no such file or directory, stat '$MY_PROJECT/.docma/api/img/tree-parent.png'

This appears to be related to setting app.routing to "path" as setting it back to "query" seems to resolve the issue.

Links on typedef's do not maintain the base path

I am noticing that typedef's do not maintain the base path when links are generated.

  "app": {
    "title": " SDK Documentation",
    "entrance": "content:readme",
    "routing": {
      "method": "path"
    },
    "base": "/pages/Development/sdk",
    "server": "github"
  },

results in

<div id="Foo~bar" class="symbol-container">
  <div class="symbol-heading">
    <div class="symbol">
      <a href="/pages/Development/sdk/api#Foo~bar">
        <svg class="svg-inline--fa fa-link fa-w-16 color-gray-light" aria-hidden="true" data-prefix="fas" data-icon="link" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" data-fa-i2svg="">...</svg>
      </a>
      <code class="symbol-name">Foo<span class="color-blue">~</span>bar(params)</code>
      <span class="symbol-sep">⇒</span>
      <code class="symbol-type">
        <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" target="_blank">Promise</a>&lt;<a href="/api/#Foo.BarResponse">Foo.BarResponse</a>&gt;</code>&nbsp;&nbsp;<span class="boxed vertical-middle bg-ice-dark opacity-full">inner</span>
      </div>
    </div>
    <div class="symbol-definition">
      <div class="symbol-info"></div>
      <p></p>
      <div class="space-top-sm space-bottom-xs fw-bold">Parameters</div>
      <ul class="param-list">
        <li>
          <div class="param-meta clearfix"><span class="inline-block space-right-sm"><code><span class="fw-bold">params</span></code>&nbsp;:&nbsp;<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" target="_blank">Object</a></code></span><span class="param-info-box"><span class="param-info required boxed">Required</span></span>
          </div>
          <div class="param-desc"><p></p></div>
        </li>
        <li>
          <div class="param-meta clearfix"><span class="inline-block space-right-sm"><code><span class="color-gray">params</span><span class="fw-bold"><span class="color-blue">.</span>items</span></code>&nbsp;:&nbsp;<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" target="_blank">Array</a>&lt;<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</a>&gt;</code></span><span class="param-info-box"><span class="param-info required boxed">Required</span></span>
          </div>
          <div class="param-desc"><p></p></div>
        </li>
      </ul>  
      <p><b class="caption">Returns:</b>&nbsp;&nbsp;<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" target="_blank">Promise</a>&lt;<a href="/api/#Foo.BarResponse">Foo.BarResponse</a>&gt;</code></p>
    </div>
  </div>

We can see that the /pages/Development/sdk/api#Foo~bar is generated correctly.. however the /api/#Foo.BarResponse link is missing the base path prefix.

Upper-cased routes produce 404

Route (names) should not be lower-cased in docma-web core.
Also, add an option for case-sensitive and insensitive routes within build configuration.

Cannot read property 'replace' of undefined

When trying to view the generated documentation of one of our projects I get a blank page and the following error in the console:

docma-web.js:32 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
helper.getSymbolInfo @ app.min.js:17
getSymbolData @ app.min.js:17
getSidebarNavItem @ app.min.js:17
(anonymous) @ app.min.js:17
helper.buildSidebarNodes @ app.min.js:17
(anonymous) @ app.min.js:17
helper.buildSidebarNodes @ app.min.js:17
(anonymous) @ app.min.js:17
dust.filter @ docma-web.js:4
Chunk.reference @ docma-web.js:4
body_0 @ docma-web.js:20
load @ docma-web.js:4
Chunk.partial @ docma-web.js:4
body_1 @ docma-web.js:13
Chunk.exists @ docma-web.js:4
body_0 @ docma-web.js:13
load @ docma-web.js:4
dust.render @ docma-web.js:4
DocmaWeb._render @ docma-web.js:32
DocmaWeb.render @ docma-web.js:32
DocmaWeb.Route.apply @ docma-web.js:34
(anonymous) @ docma-web.js:43
setTimeout (async)
(anonymous) @ docma-web.js:43
(anonymous) @ docma-web.js:9
o @ docma-web.js:9
(anonymous) @ docma-web.js:9
o @ docma-web.js:9
L.dispatch @ docma-web.js:9
L.replace @ docma-web.js:9
L.start @ docma-web.js:9
window.onload @ docma-web.js:43
load (async)
(anonymous) @ docma-web.js:43
(anonymous) @ docma-web.js:43

Looking into the file, this seems to be due to the kind.replace call. Replacing this with (kind || "unknown").replace resolves the issue.

It appears this problem is caused by having a (non-exported) documented top-level variable. For example:

/**
 * This is a constant.
 */
const CONSTANT = 42;

New template

Just to let you know the documentation for AthenaJS is now using Docma with a new template (which is based on Docma's default template) and is available here :)

Add class inheritance diagrams

Hi there,

I suggest adding a class (ECMAScript 2015) inheritance diagram for each class (similar like doxygen or other libs).
This could be quite fancy!

Uncaught TypeError: Cannot read property 'names' of undefined

This bit of code:

.addFilter("$returns", function(symbol) {
        var returns = Array.isArray(symbol) ? symbol : symbol.returns;
        return DocmaWeb.Utils.getFormattedTypeList(docma.apis, returns, {
            delimeter: "|",
            descriptions: true,
            links: templateOpts.symbols.autoLink
        })
    })

Is called, and returns value is: [{description: "Object"}]

When this line is executed:

docma/lib/web/DocmaWeb.Utils.js

Line 1130 in 464fe5b

var types = item.type.names;

item is {description: "Object"} has a type of undefined, which causes this error.

Static definitions inside a ES2015 class cause errors

This :

class FullScreenButton extends React.Component {
    static propTypes = {

Causes an error like:

ERROR: Unable to parse /......./FullScreenButton.jsx: Unexpected token =

Also this fails:

getButtonProperties = () => {
// ...
}

cli and config file formats

If using the cli the config file must be straight json? yaml supported? If not yaml then I suppose I have to use the api to build so I can import the config as js (and thus comment it).

Default value of param is parsed as `undefined` in template

Boolean symbol parameters' default value is parsed as undefined (if value is false). It should be checked with hasOwnProperty(param.defaultValue).

Cannot generate any API files: null contentPath

I tried to clone this repository, and simply ran npm install && npm run docs in order to generate the documentation.
It first failed because the file ./doc/HOME.md doesn't exist:

ENOENT: no such file or directory, open '/Volumes/HDD2/Docs/Dev/docma/doc/HOME.md'

After fixing it by simply replacing it by ./README.md in docma.json which exists, the docs are generated, but the content path is null for every api file:

Configured SPA Routes:

type     name             path                   contentPath
-------  ---------------  ---------------------  ----------------------
api      _def_            /?api                  null
api      docma            /?api=docma            null
api      docma-web        /?api=docma-web        null
api      docma-web-utils  /?api=docma-web-utils  null
content  changelog        /?content=changelog    content/changelog.html
content  md-test          /?content=md-test      content/md-test.html
content  guide            /?content=guide        content/guide.html

What's wrong?

I tried to create a very simple config file and I am having the same problem.

Support ES7 Async/Await

node docma.js
Error: ERROR: Unable to parse C:\Users\macdja38\WebstormProjects\pvpcraft\lib\MessageSender.js:  Unexpected token _getWebhook

    at ChildProcess.<anonymous> (C:\Users\macdja38\WebstormProjects\pvpcraft\node_modules\jsdoc-x\src\lib\helper.js:143:35)
    at emitTwo (events.js:106:13)
    at ChildProcess.emit (events.js:192:7)
    at maybeClose (internal/child_process.js:890:16)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:226:5)

Where _getWebhook is declaired as

async _getWebhook(channel)

Script tags are not loaded when loading HTML content

Hello, firstly, thank you for your work. 👍

The issue is that none of my JS scripts are loaded when I'm trying to load a HTML file to complete my documentation.
For example I am trying to load a demonstration with a bundle.js file (bundled with webpack) in the HTML file:

<div id="demo"></div>
<script type='text/javascript' src='bundle.js'></script>

The docma.json config file:

{
  "debug": 1,
  "clean": true,
  "src": [
    "./src/*.js",
    "./README.md",
    "./examples/demo.html"
  ],
  "serverType": "apache",
  "app": {
    "title": "mytitle",
    "logo": {
      "dark": "/static/img/redc.png"
    },
    "routing": "path",
    "entrance": "content:readme",
    "base": "/"
  },
  "dest": "./examples/documentation/",
  "template": {
    "path": "zebra",
    "options": {
      "title": {
        "label": "mytitle",
        "href": "/"
      },
      "logo": {
        "dark": "/static/img/redc.png",
        "light": "/static/img/redc.png"
      },
      "sidebar": {
        "enabled": true,
        "outline": "tree",
        "collapsed": false,
        "toolbar": true,
        "itemsFolded": false,
        "itemsOverflow": "crop",
        "badges": true,
        "search": true,
        "animations": true
      },
      "symbols": {
        "autoLink": true,
        "params": "list",
        "enums": "list",
        "props": "list",
        "meta": false
      },
      "contentView": {
        "bookmarks": "h1,h2,h3"
      },
      "navbar": {
        "enabled": true,
        "fixed": true,
        "dark": false,
        "animations": true,
        "menu": [
          {
            "label": "Demonstration",
            "href": "/demo"
            }]
          }
        }
      },
      "assets": {
        "/static/img": ["./examples/documentation/img/*.*"]
      }
    }

Output of routes constructed using docma:

Configured SPA Routes:

type     name    path     contentPath          sourceType
-------  ------  -------  -------------------  ----------
api      _def_   /api     —                    js
content  readme  /readme  content/readme.html  md
content  demo    /demo    content/demo.html    html

So accessing the link /demo is not working because scripts are not loaded.
But accessing content into /content/demo.html loads scripts as expected but with a wrong URL script as it expects a /content/bundle.js instead of /bundle.js.

So my question is, are scripts loaded when you are loading HTML files or is this a bug?

Edit: My bundle.js file is available at /bundle.js ;)

CLI

Any CLI planned?

Description removes Windows-style newlines.

Let's say I have a description like this one:

/**
 * line 1
 *
 * line 2
**/
class foo {
}

If I save the file with Windows line-endings (CRLF), the generated symbol.description will be:

line1line2

Which will end up rendering this description html:

<p>line1line2</p>

If I save the save file with Unix line-endings (LF), the symbol.description will be correct:

line1

line2

Which end up rendering this description html:

<p>line1</p>
<p>line2</p>

onury / docma Goto Github PK

docma's People

Contributors

Stargazers

Watchers

Forkers

docma's Issues

Problem

Image Examples:

Code Snippet Examples:

Recommend Projects

Recommend Topics

Recommend Org