onury / docma Goto Github PK
View Code? Open in Web Editor NEWA powerful tool to easily generate beautiful HTML documentation from JavaScript (JSDoc), Markdown and HTML files.
Home Page: https://onury.io/docma
License: MIT License
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
command line docma -c docma.json
there is a error:
$ is not a function
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).
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.
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
item
is {description: "Object"}
has a type
of undefined
, which causes this error.
Route (names) should not be lower-cased in docma-web core.
Also, add an option for case-sensitive and insensitive routes within build configuration.
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.
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)
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",
}
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.
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.
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 ?
This :
class FullScreenButton extends React.Component {
static propTypes = {
Causes an error like:
ERROR: Unable to parse /......./FullScreenButton.jsx: Unexpected token =
Also this fails:
getButtonProperties = () => {
// ...
}
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><<a href="/api/#Foo.BarResponse">Foo.BarResponse</a>></code> <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> : <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> : <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" target="_blank">Array</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string" target="_blank">string</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>
</ul>
<p><b class="caption">Returns:</b> <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" target="_blank">Promise</a><<a href="/api/#Foo.BarResponse">Foo.BarResponse</a>></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.
/**
* Test Class
* @emits myEvent - Desc
*/
class Test extends EventEmitter {
}
The @emits
attrib is not in the generated api doc.
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
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/
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)
})
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?
Code organized by namespace
is not sorted or grouped correctly.
namespace
:namespace
: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 {
...
}
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?
In the default template, symbols with @deprecated
tag should either be faded or have a warning shown. This could be configurable.
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)
Boolean symbol parameters' default value is parsed as undefined
(if value is false
). It should be checked with hasOwnProperty(param.defaultValue)
.
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.
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!
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)
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.
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
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?
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
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.
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.
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;
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'
});
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?
Any CLI planned?
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"
]
}
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.
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?
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.
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.
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 ;)
I found that the following methods were not documented:
Since there are used in the default template's filters ($returns
, $extends
, $exceptions
) I think it would be a good idea to add them.
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:
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
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>
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:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.