I created a new HTML template for the Javascript documentation tool JSDoc, which is now free for download. It is tested in IE6 to IE9, FF3.6, Chrome 5 and Safari 4.
The template is based on the basic template of JSDoc Toolkit. The HTML structure is basically the same, but with a new design for both desktop and mobile browsers.
Command line options
- Set title
-D="title:Estate Library" - Remove _global_
-D="noGlobal:true" - Make “Files” the homepage instead of “Classes”
-D="index:files"
Example:
java -jar jsdoc-toolkit\jsrun.jar jsdoc-toolkit\app\run.js -d=Documentation\ -D="noGlobal:true" -D="title:Estate Library" -D="index:files" -t=jsdoc-toolkit\templates\codeview -p -v Javascript\Estate\Source\Estate*.js
Screenshots (version 1.1.2)
Codeview for desktops
Codeview for handheld devices
Changelog:
-
1.2
- Extra command line options, thanks to Aaron Wirtz
- A more logical template structure, thanks to Aaron Wirtz
- A quick filter, to filter the class list and methods
- Some bug fixes, including one reported by Gregor -
1.1.2
- Option for removing the _global_ link by adding-D="noGlobal:true"in the command line -
1.1.1
- Styling fixes -
1.1
- Support for mobile devices
- Updated design and styling fixes
Awesome! I just used it. so much nicer than the original JsDoc Toolkit template.
Good job!
*blush* Thank you. Just let me know if something goes wrong. I want to update the theme in a few months.
Nice, couldn’t be better
using it for my next script 
Thanks for the work you have put in it.
Hey Wouter,
Really liked the look of your codeview template, so I took a crack at integrating it into my build process. Its head and shoulders above the default template that comes shipped with jsdoc – everything seems nicely spaced out and clean.
One change I might suggest would be to put a overflow-x:auto or max-width on the li elements in the ‘classList’ ul. I have some pretty verbose class names and they are overflowing into the main pane in a few places.
Other than that very small issue – thanks for making this template available.
Sean
*blush again* Thank you for the compliments. I indeed didn’t just style the HTML, I also spent some time styling the code as well. Nice that people can appreciate it. I’m going to add some more features to the template soon. I definitely will add some solution to the overflow issue as well, because it’s also a problem for my classes
It’s really clean and easy to read, totally awesome. My docs just became a lot more useful. Thanks for making this!
Hi,
I’m trying to use your template. It seems like everyone knows what they are doing, I guess i”m the dumb one. How do i take your files and implement to the current default styling that I have? Do I just download and take your files and copy over to the existing one?
Thanks much!
James
@James: we all have to figure out how things work, so no need for apologies
What you must do is download the template and add it to the template folder of JsDoc Toolkit (\jsdoc-toolkit\templates). After that I run the following command in DOS prompt:
java -jar jsdoc-toolkit\jsrun.jar jsdoc-toolkit\app\run.js Javascript\Estate\Source\Estate*.js -d=Documentation\ -t=jsdoc-toolkit\templates\codeview -p -vBy the way:
Javascript\Estate\Source\is the path of my own code library.Let me know this clears thing up for you.
I’m using jsdoctoolkit to document a library which contains no components in the global namespace (as well it should not!), and as such the automatic inclusion of the “_global_” link in the class list has been bothering me. So here is a patch to your template to allow its suppression:
— codeview/allclasses.tmpl 2010-09-27 21:57:48.000000000 +0000
+++ templates/codeview/allclasses.tmpl 2010-11-07 05:44:31.000000000 +0000
@@ -9,2 +9,3 @@
+ {! if(thisClass.alias != ‘_global_’ || !JSDOC.opt.D.noGlobal) { !}
{!
@@ -13,2 +14,3 @@
!}
+ {! } !}
Once applied, this patch will allow you to specify -D=”noGlobal:true” on the jsdoc commandline to suppress inclusion of the “_global_” link in the class list.
Cheers!
Thanks for the tip. I added it to the template and updated it to 1.1.2. I find the _global_ options annoying as well, but it has its use. Without it you never know for sure if a library creates some global variables or not.
hey, thanks for the template… noGlobal doesn’t work for me here… but this is a minor.
running your template on a linux server i’ve got a case sensitive bug with the file: wbos.csstools.mediaqueryfallback.js
gregor.patchIndex: jsdoc_toolkit-2.3.2/templates/codeview/class.tmpl
===================================================================
— jsdoc_toolkit-2.3.2/templates/codeview/class.tmpl (revision 12)
+++ jsdoc_toolkit-2.3.2/templates/codeview/class.tmpl (working copy)
@@ -14,7 +14,7 @@
-
+
Index: jsdoc_toolkit-2.3.2/templates/codeview/index.tmpl
===================================================================
— jsdoc_toolkit-2.3.2/templates/codeview/index.tmpl (revision 12)
+++ jsdoc_toolkit-2.3.2/templates/codeview/index.tmpl (working copy)
@@ -13,7 +13,7 @@
-
+
@@ -53,4 +53,4 @@
wbos.CssTools.MediaQueryFallBack.LoadCss(’css/screen.css’, ‘css/handheld.css’, 660)
-
\ No newline at end of file
+
Index: jsdoc_toolkit-2.3.2/templates/codeview/allfiles.tmpl
===================================================================
— jsdoc_toolkit-2.3.2/templates/codeview/allfiles.tmpl (revision 12)
+++ jsdoc_toolkit-2.3.2/templates/codeview/allfiles.tmpl (working copy)
@@ -14,7 +14,7 @@
-
+
@@ -73,4 +73,4 @@
wbos.CssTools.MediaQueryFallBack.LoadCss(’css/screen.css’, ‘css/handheld.css’, 660)
-
\ No newline at end of file
+
regards,
gregor
Thanks for the bug report. I fixed the bug in version 1.2 that’s now available for download!
I’m getting the error couldn’t open file jsdoc-toolkit/templates/codereview/publish.js with jsdoc-toolkit 2.3.2. I’ve tried various different ways of specifying the template relative, absolute, or named template. They all seem to end in the same error. I renamed the standard template to ‘fun’ and called ‘fun’ this worked fine. Not sure what the real error here is.
js: Couldn’t open file “jsdoc-toolkit/templates/codereview/publish.js”.
>> WARNING: Sorry, that doesn’t seem to be a valid template: jsdoc-toolkit/templates/codereview/publish.js : ReferenceError: “publish” is not defined.
Also,
js: Couldn’t open file “codereview/publish.js”.
I figured out my problem, thanks this works great
Thank you. I’m happy you have worked out that problem!
Hi,
thank you very much for this great template!
May I suggest a small feature for a future version? I modified the template for my purposes to exclude the “files” link in the menu and the “Defined in” references in class pages. Then I use the jsdoc option -s in order to omit any source code in the output. I think it really would be nice to have an option to omit the “files” link and “Defined in” references. Maybe it is even possible to automatically omit them, then when the jsdoc option -s was given.
First of all, thanks a lot for this template Wouter, it looks great!
Second I have some questions:
- I couldn’t get my javascript code syntax colored, is this not supported or I am doing something wrong?
- On Google Chrome 10 I’m getting some errors:
“Viewport argument “width” not recognized. Content ignored.
Viewport argument “initial-scale” not recognized. Content ignored.
Viewport argument “maximum-scale” not recognized. Content ignored.”
Regards
Wouter I took the liberty of modifying your template adding syntax highlighting using http://alexgorbatchev.com/SyntaxHighlighter/
It works great, If you want I can send you the patch.
Sounds great! I’d like to see your patch!
Thanks. I’ll look into this
(Sorry for the delay)
I publish the modified template at my javascript library project on GitHub, its here:
https://github.com/benjamine/tent/tree/master/jsdoc-toolkit/templates
there is a folder with the original codeview, and another named codeview-syntaxhighlight/
basically the changes a made are:
class.tmpl > modify class in all code examples this way:
{+example+}
——————–
foot.tmpl > add syntax highlighting init:
// Syntax Highlighting
SyntaxHighlighter.all();
————–
head.tmpl > add references to .js and .css files in this block:
—————-
Add the files referenced on head.tmpl:
css/shCore.css
css/shThemeDefault.css
javascript/shCore.js
javascript/shBrushJScript.js
Note: shThemeDefault.css can be replace to get some diferent styles, themes can be download from:
http://alexgorbatchev.com/SyntaxHighlighter/
As an example you can check this doc page I uploaded (there’s code at the bottom):
http://benjamine.github.com/tent/docs/api/symbols/tent.entities.Context.html
Ops, xml tags dissapeared,
- class in pre tags is :”code brush: js”
- the block of added references can be checked here (under “Syntax Highlighting” comment):
https://github.com/benjamine/tent/blob/master/jsdoc-toolkit/templates/codeview-syntaxhighlight/subtemplates/head.tmpl
Thanks for providing this- it looks great.
I have a longshot question for you about jsdoc. I’m trying to get the –exclude option working to exclude all js files that start with a certain string. The problem is I can seem to stumble upon the right regex expression to make this work. Any suggestions?
Sorry, but I’m no good with that either. You’ll most likely get a sane answer at http://groups.google.com/group/jsdoc-2
Thanks for your template, I have applied it to my project.
Code syntax coloring is not supported at the moment. The problem is that some people (well, me at least) do not just add JavaScript to the code example but also the accompanying HTML. I might build it into the template someday and make it optional.
I fixed the Google Chrome 10. The new Codeview is downloadable from Github: https://github.com/WouterBos/Codeview
…And sorry for the late reply…
Looks great, love it, Amazing job
Thanks!
Amazing!!! Does this template work fine in JSDOC3?
Thanks Jeaf!
No, it does not work in JSDOC3. That is: I presume it won’t work. I might make a port for JSDOC3 by the time it’s out beta.
Thumbs up! Thanks a bunch for sharing
good!
one bug:
“Generated on” month is incorrect,it give us previous month
I got a bug report via Github. It’s fixed now.
This is awesome.
So much better than the default template!
Thanks Wouter.
I am new to JSDoc and wondering if I can somehow tweak this template to output XML instead of HTML.
What do i need to do in order to get that?
Just specifiying the output ext. wont help I guess!
I’m sorry. The template is purely an HTML template. There is no switch to generate XML instead.