π go check out my website instead
clenemt / docdash Goto Github PK
View Code? Open in Web Editor NEW:zap: Lodash inspired JSDoc 3 template/theme
Home Page: http://clenemt.github.io/docdash/
License: Other
:zap: Lodash inspired JSDoc 3 template/theme
Home Page: http://clenemt.github.io/docdash/
License: Other
π go check out my website instead
Hello,
I'm missing support for configuration option templates.default.useLongnameInNav
(JSDoc documentation).
For example, there are two classes Foo
and Bar
. If I define that Bar
is @memberof Foo
, then the Bar
class heading if correctly showing Foo.Bar
. But in the nav bar there is only Bar
shown despite being sorted as if it had name Foo.Bar
(i will output Bar
item just after Foo
).
This should be good to have the choice between a table or new lines for parameters
In my project I did this:
<?js
var isChild = false
var origin = ''
if (typeof obj === 'object' && obj !== null && obj.subparams) {
origin = obj.path + '.'
obj = obj.subparams
isChild = true
}
var params = obj
function escapeRegExp(string) {
return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
/* sort subparams under their parent params (like opts.classname) */
var parentParam = null
params.forEach(function(param, i) {
var paramRegExp
if (!param) {
return
}
param.fullname = origin + param.name
if (parentParam && parentParam.name && param.name) {
try {
paramRegExp = new RegExp('^(?:' + escapeRegExp(parentParam.name) + '(?:\\[\\])*)\\.(.+)$')
}
catch (e) {
console.error('Problem parsing comment', e)
// there's probably a typo in the JSDoc comment that resulted in a weird
// parameter name
return
}
if ( paramRegExp.test(param.name) ) {
param.name = RegExp.$1
parentParam.subparams = parentParam.subparams || []
parentParam.subparams.push(param)
params[i] = null
}
else {
parentParam = param
}
}
else {
parentParam = param
}
})
?>
<dl>
<?js if (isChild) { ?>
<h6>Sub properties</h6>
<?js } ?>
<?js
var self = this
params.forEach(function(param) {
if (!param) { return }
?>
<dt>
<code class="parameter"><?js= param.fullname ?></code>
<?js if (param.type && param.type.names) {?>
<?js= self.partial('type.tmpl', param.type.names) ?>
<?js } ?>
</dt>
<dd class="para">
<?js if (params.hasAttributes) {?>
<?js if (param.optional) { ?>
<optional><br>
<?js } ?>
<?js if (param.nullable) { ?>
<nullable><br>
<?js } ?>
<?js if (param.variable) { ?>
<repeatable><br>
<?js } ?>
<?js } ?>
<?js if (params.hasDefault) {?>
<?js if (typeof param.defaultvalue !== 'undefined') { ?>
<code><?js= self.htmlsafe(param.defaultvalue) ?></code>
<?js } ?>
<?js } ?>
<?js= param.description ?></p>
<?js if (param.subparams) { ?>
<?js= self.partial('params.tmpl', { 'subparams': param.subparams, 'path': param.fullname }) ?>
<?js } ?>
</dd>
<?js }) ?>
</dl>
config (with jsdoc/jsdoc#1771 ):
{
"opts": {
"destination": "./gh-pages/",
"tutorials": "./docs/",
"template": "node_modules/docdash"
},
// ...
"templates": {
"default": {
"staticFiles": {
"include": [
"./docs/home/custom.css"
]
}
},
"overwrite": {
"node_modules/docdash/tmpl/params.tmpl": "docs/home/tmpl/params.tmpl"
}
}
}
When you have empty lines in your source code, they are removed from the source code view in the template.
Linux
JSDoc supports use of the @generator
and @yields
tags to support documentation for generators. The @generator
tag is already (sort-of) understood by docdash, but the @yields
tag is not.
In order to properly support documenting generators, support for the @yields
tag should be added.
I suggest treating it very similarly to a @returns
tag; the above example would say, for example, (async, generator) getFollowing() β {string}
, and below the method description, there would be a "Returns: Type - String" section.
How can I add or customize my language? For example, Russian.
Awesome template by the way.
The line says "template": "node_modules/dodash" when it should say "template": "node_modules/docdash"
First, thanks for this very nice template. Love it.
However, we have a small issue with the documentation. In general, our 'api' is assembled from smaller functions using an index, that also exports the functions as part of the API.
/**
* @module modeling/expansions
*/
module.exports = {
expand: require('./expand'),
offset: require('./offset')
}
The documentation produced always has the 'static' keyword in front of the documentation.
(static) offset(options, β¦geometry) β {Object|Array}
In our case, it would be nice to disable the 'static' keyword from appearing in the documentation.
Should be able to display a preview from the fixtures folder.
Hello,
I'm looking to use jsdoc and docdash to generate JavaScript documentation for an enterprise application. I need to be able to override the styles to match company branding yet keep the overall layout the same. Is there anything built in so that I can include my own styles into the template? Perhaps in the config file?
ink-docstrap has a nice feature where it's possible to disable method sorting by specifying
{"opts": {"sort": false}}
in the config file. JSDoc seems to sort methods alphabetically by default, but it's often preferred to display functions in the same order that they appear in the source code.
Would it be possible to add this feature to docdash?
I was trying to create a JS documentation for my Node-express application.
followed the steps as mentioned in
https://github.com/clenemt/docdash
Below is the snap representing Package.json
The JsDoc.json is as follows
{
"source": {
"include": [
"./controller/index.js",
"./middleware/",
"./utility/",
"./routes/index.js"
]
},
"tags":{
"allowUnknownTags":true,
"dictionaries":[
"jsdoc"
]
},
"plugins":[
"plugins/markdown",
"plugins/shout"
],
"markdown":{
"idInHeadings":true,
"hardwrap":true
},
"opts":{
"template":"node_modules/docdash/",
"encoding":"utf8",
"destination":"./documentation/",
"recurse":true,
"verbose":true
},
"templates":{
"cleverLinks":true,
"monospaceLinks":true
},
"docdash":{
"collapse":true,
"search":true
}
}
While generating the docs using the npm run generate-docs script
getting the error as below.
Kindly help to resolve this
Hi, great plugin!
I think one missing feature I'd love to see is an option to toggle those es6 get/set properties to be visible in the side nav. Or is this something that jsdoc will have to implement for you to parse?
Thank you!
Each class should also be collapsible.
Opening the demo page on an iPhone 8 or iPhone X (probably also on others) leads to clipped text rendering.
In Safari on iPhone X it looks like this:
This can also be reproduced in Chrome by simulating an iPhone X via DevTools -> "Toggle device toolbar" (in the upper left corner) -> iPhone X -> Open http://clenemt.github.io/docdash/
I was wondering if docdash has the option or would accept a PR to config the theme accent color?
It would be nice to be able to collapse sections for the case of projects with large number of classes/namespace/...
Version 1.2 allows to collapse object members but no the top section (namespace, events, classes...)
publish.js:305
needs something akin the following added above:
if (members.length) {
itemsNav += "<ul class='members'>";
members.forEach(function (member) {
itemsNav += "<li data-type='member'>";
itemsNav += linkto(member.longname, member.name);
itemsNav += "</li>";
});
itemsNav += "</ul>";
}
Would also be nice to have some (static)
flair or something on the members to distinguish them from methods.
Global section is not available to put on order.
It only adds "undefined" menu item as text.
I was following the docs for configuring docdash with jsdoc but the link that specify how to turn on line number is not working
- linenums
When true, line numbers will appear in the source code listing. If you have
also turned that on.
The website seems to be down
I have a table that displays information about a given algorithm. I expected the table to have divisions and the columns to be respected. This does not seem to happen.
Following is an example using bubble sort.
/**
* @namespace Quadratic.bubble
* @desc
* Some description about bubble sort here
*
* | Sort Type | Best-case perf. | Worst-case perf. | Average perf. | Worst-case space perf. | Stable |
* | :-------------- | :-------------- | :--------------- | :------------ | :--------------------- | :----- |
* | Comparison Sort | O(n) | O(nΛ2) | O(nΛ2) | O(1) aux | Yes |
*
* .... more stuff
*/
As you can see, this is a markdown table.
This is what the page displays:
As you can see the table has no divisions whatsoever. It is also not clear where a given column begins and ends.
Converting the code to HTML has no difference ( as expected ).
Access to fonts.googleapis.com is blocked by the firewall where my generated jsdoc is accessed. Is there a way of replacing or dropping this dependency entirely? At the moment because the hostname cannot resolve the page loads take over 20 seconds.
Is there a way to autodetect the structure as documentation.js does (without using @Class, @method and @memberof), or is there a way to make this theme work with documentation.js ?
Thanks
example:
/**
* my product class
*/
class Product () {
/**
* my 1st method
*/
method1 () {}
/**
* my 2nd method
*/
method2 () {}
}
expected documentation's left bar:
CLASSES
Product
| method1
| method2
thanks.
The description you put in the comments for a namespace is right at the bottom of the page. Is there a possibility to place it at the top, say make it look more like the method section (remove the purple bar then). So you get 'title', 'attributes', 'description', 'properties'
#86
See tags aren't linked and the resulting corresponding html code contains no <a>
. Probably because in the details.tmpl
:
<?js if (data.see && see.length) {?>
<dt class="tag-see">See:</dt>
<dd class="tag-see">
<ul><?js see.forEach(function(s) { ?>
<li><?js= self.linkto(s) ?></li>
<?js }); ?></ul>
</dd>
<?js } ?>
self.linkto(s)
would not produce a link, because s
is not a URL?
Just a question, the default jsdoc template includes a package's version on the home page. Would you be open to a PR adding that to the docdash template?
Hi,
On a quite big js project, generated documentation is 1224 files of 2Mo each (2,3Go). It's because the
part has a weight of 1.9Mo.Having only one <nav>
content for all files could reduce a lot the total weight, here around 200 times less (1224Γ2000
vs 1900 + 1224Γ100
, in my case from 2.3Go to ~125Mo).
It could be done with a frameset, or an ajax call to populate the nav bar in each html page (the nav.html will be in the browser cache after the first call).
Is such an enhancement can be put on the roadmap ?
BTW, thanks a lot for this great template.
Now, when you publish, static assets end up in sub folders. This means the template cannot load files properly.
Expected: scripts/prettify/prettify.js
Actual: scripts/prettify/prettify.js/prettify.js
I'm trying to mark a constructor as private, but it still shows up in the generated documentation with either or both of hideconstructor and private.
/**
* Class description
* @hideconstructor
*/
class MyClass {
/**
* @private
*/
constructor() {}
}
Is there another way to do it or is it not supported right now? If the later, any chance of supporting it?
With the removal of jquery in the latest version, the search no longer works in IE11. When trying to search, it gives above error in console.
The problem occures in search.js#contains()
method,
return (a.textContent || a.innerText || "").toUpperCase().includes(m)
I use ESLint which enforces a hard limit of 120 characters on line width. The generated documentation replicates the exact line widths in my source code, which is suboptimal (for example, on mobile there is a lot of superfluous wrapping, and on large monitors the available width is not used.)
Is there a way to ignore the carriage returns when generating the HTML?
Thanks!
conf.json:
{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"opts": {
"template": "node_modules/docdash",
"destination": "./gen-jsdoc"
},
"plugins": ["plugins/markdown"],
"templates": {
"___options-doku:": "https://github.com/docstrap/docstrap#options",
"includeDate": "true",
"navType": "vertical",
"theme": "lumen",
"linenums": "true",
"collapseSymbols": "true",
"outputSourceFiles": "false",
"outputSourcePath": "false",
"dateFormat": "YYYY-MM-DD",
"search": "true",
"cleverLinks": true,
"monospaceLinks": true
}
}
gulp snippet:
gulp.task('generate-jsdoc', function(cb) {
var config = require('./src/main/resources/template/conf.json');
gulp.src([ './target/*.js' ], {
read : false
}).pipe($.jsdoc3(config, cb));
});
result:
β DataObjectUtils-x.x.x-SNAPSHOT.js.html
β global.html
β index.html
β ISI.html
β namespaces.list.html
β quicksearch.html
β
ββββfonts
ββββimg
ββββscripts
ββββstyles
Looks like you've been actively developing but the npm package is 2 years old. Is it time for a publish?
I just started using docdash after reviewing a few themes for JsDoc and think it's the best one out there. Here's my site:
and the underlying repo:
https://github.com/radgrad/datamodel
I'm not sure how hard this would be, but one significant improvement to my documentation would be to create a way to add sections in the home page (in my case, my README.md) to the navbar. So, instead of just "Home", the navbar would contain:
Home
Overview
Development procedures and scripts
...
There are TOC packages for markdown, so maybe it wouldn't be too bad.
Thanks for your consideration, and thanks for releasing such a nice package to the community.
I want to add a search bar in the navigation pane to search any API like we have in other JS doc template particularly 'Jaguar'.
@example
code could provide a link to online editors using their post API, see for example stackblitz post-api or codepen prefill.
By default when package.json provided, package name (and scope) and version is added to the output path. I'd like to keep version, but name and especially scope folder is unnecessary. It would be great if it can be done.
I have tried several other JSDoc (v3.5.5) template packages found on Npm, and they generate the docs without issue. However, I ran into a hard error when first using this template:
Parsing /path/to/Workspaces/myproject/externals.jsdoc ...
Parsing /path/to/Workspaces/myproject/modules.jsdoc ...
Generating output files...
/path/to/Workspaces/myproject/node_modules/docdash/publish.js:335
if (item.ancestors.length > level) {
^
TypeError: Cannot read property 'length' of undefined
Changing that line to if (item.ancestors && item.ancestors.length > level) {
then allowed the generation to run. I actually have several directories of files with docs but the above shows that paring down the list to very few docs was still resulting in the same error. Everything is running on node v10.15.1.
Hi docdash team.
First of all, I'm very happy to use your awesome template for my javascript project. Thank you so much for doing docdash.
I have a question. Is it possible to display member of class in table of content?
Hello,
in my javascript code:
* @example
* const cluster = new couchbase.Cluster('couchbase://127.0.0.1');
* const bucket = cluster.openBucket('default');
* const driver = Driver.create(bucket);
Output:
If I place the example comment code with newlines in between each line, than the output does get separated into new lines but there are still the <p>
and <br>
tags in the output.
my jsdoc.json file:
{
"tags": {
"allowUnknownTags": true
},
"plugins": ["plugins/markdown"],
"source": {
"include": "./lib",
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"templates": {
"cleverLinks": true,
"monospaceLinks": true,
"default": {
"outputSourceFiles": true
},
"linenums": true
},
"opts": {
"template": "node_modules/docdash",
"destination": "docs/",
"recurse": true
},
"markdown": {
"parser": "gfm",
"hardwrap": true,
"tags": ["examples"]
}
}
This doesn't seem to happen with other templates.
Thanks.
I just wanted to say thank you for this JSdoc theme! We took it an customized if for docs.actionherojs.com
Modern browsers do not need it anymore, and you really can get rid of itβ¦
hello, recently I used the docdash template in my documentation with JSDoc (and I really liked it, congratulations!), but I wanted to know how I TOTALLY change the background color, I already tried to change everything I found, however, it is not right, there are several white parts. Thank you for your attention, and congratulations!
Hi,
it seems the following three options are not working properly:
scopeInOutputPath: [false|true], // Add scope from package file (if present) to the output path, true by default.
nameInOutputPath: [false|true], // Add name from package file to the output path, true by default.
versionInOutputPath: [false|true] // Add package version to the output path, true by default.
I am trying to create the output in a directory, namely "public", without the subpath "@mygroup/myproject/1.0.0".
From the documentation, I understand the previous three options should do the trick, by setting them to false.
Unfortunately, this is not the case.
I am using jsdoc 3.6.5 and docdash 1.2.0.
Regards.
I want to disable private in navigation menu. I try docdash.private
or docdash.static
but they don't make any change.
jsdoc.json:
{
"opts": {
"destination": "./.doc/",
"private": true,
"template": "node_modules/docdash",
"readme": "README.md",
"tutorials": "doc/",
"package": "package.json"
},
"docdash": {
"private": false
}
}
gulpfile.js:
const path = require('path')
const del = require('del')
const gulp = require('gulp')
const jsdoc = require('gulp-jsdoc3')
const normalizeSEP = (str) => str.replace(/\//g, path.sep)
process.chdir(path.resolve(__dirname))
const docFolder = path.resolve(__dirname, '.doc')
const cleanDoc = () => del([
docFolder
])
const src = [
'./bin/**/*.js'
].map(normalizeSEP)
const generateDoc = () =>
gulp.src(src, {read: false})
.pipe(jsdoc(require('./jsdoc.json')))
gulp.task('doc', gulp.series(cleanDoc, generateDoc))
My script :
/**
* This function load a specific CSS Engine.
*
* @private
* @memberof AppExpress
* @param {string} engine Name of engine to add
*/
function registerCSSEngine(engine) {
Hi, first of all I really like how docdash looks and how it organizes the classes and modules.
JSDOC 3 link extended classes so you can click to see the parent class. I think this linkage is very important.
I don't see any issue openen or closed since a while. Is this project abandoned?
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.