npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jsdoxy

v0.13.0

Published

jsdoc documentation generator

Downloads

34

Readme

jsdoxy

A jsdoc-ish documentation generator forked from visionmedia/dox.

Differences from visionmedia/dox

  • Allows multiline tag comments.
  • Supports code context on string key properties like someobject['asdf-jkl'].
  • Code context and parsing for more things:
    • @event
    • @fires
    • @auth
    • @augments
  • Uses a supported markdown parser (marked) instead of the old deprecated one.
  • Includes a grunt plugin jsdoxy.
    • Comments are organized into a plain object with the @class MyClass tag as the key.
    • Optionally renders the JSON output using Jade.

Usage

Note You must use the @class comment as your first comment per file. @class myClass is used to organize the output (this is different than the original Dox project. If you fail to do this, you will have no output.

Globally

One file at a time.

npm install -g jsdoxy

You can do this from the terminal

$>  jsdoxy --help

  Usage: jsdoxy [options]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -r, --raw      output "raw" comments, leaving the markdown intact
    -a, --api      output markdown readme documentation
    -d, --debug    output parsed comments for debugging

  Examples:

    # stdin
    $ jsdoxy > myfile.json

    # operates over stdio
    $ jsdoxy < myfile.js > myfile.json

Grunt plugin

Multiple files at a time, organizing the output by the @class tag, optionally rendered using a jade template.

Install the package to your project with NPM

npm install jsdoxy --save-dev

then in your source code, the @class tag should always be part of the first comment

	/**
	 * A class that does something.
	 *
	 * Use it in this way.
	 * @class MyClass
	 * @param object opts Some parameters to get you started.
	 */
	function MyClass (opts) {
		. . .
	}

then inside Gruntfile.js at the project root

    grunt.loadNpmTasks('jsdoxy');

    grunt.initConfig({
		jsdoxy: {
            options: {
				// JSON data representing your code. Not optional.
            	jsonOutput: 'jsdoxy-output.json',

				// A Jade template which will receive the locals below. Optional.
				// Set to `false` to disable building this template. Other falsey values
				// will use the default template.
				template: 'your-template.jade',
				// when using a template, what is the base path for all of the links
				// to work from?
				basePath: '', // '/docs'

            	// Indicates whether to output things marked @private when building docs
				outputPrivate: false,
				// make an index landing page
				generateIndex: false,
				// flatten the outputted files into one directory
				flatten: false,
				// path to a custom stylesheet
				stylesheet: "https://maxcdn.bootstrapcdn.com/bootswatch/3.3.4/paper/bootstrap.min.css"
            },
            files: {
                src: [ . . . ],
                dest: '. . .'
            }
        }
	});

yields jsdoxy-output.json

	{
		"MyClass": {
	        "tags": [
	            {
	                "type": "class",
	                "string": "MyClass"
	            },
	            {
	                "type": "param",
	                "types": [
	                    "object"
	                ],
	                "name": "opts",
	                "description": "Some parameters to get you started."
	            }
	         ],
			 "returns": "Object || String",
			 "fires": [{ "type": "fires", "string": "some-event" }],
	         "description": {
	           "full": "<p>A class that does something.</p><p>Use it in this way.</p>",
	           "summary": "<p>A class that does something.</p>",
			   "body": "<p>Use it in this way.</p>"
	        },
	        "isPrivate": false,
	        "ignore": false,
	        "code": "function MyClass(opts) { . . . }",
	        "ctx": {
	            "type": "declaration",
	            "name": "MyClass",
	            "string": "idk what goes here",
	            "file": {
	            	"input": "./input/file/path/file.js",
	            	"output": "./output/file/path/file.js.json"
	            }
	        }
	    }
	}

Jade template

There is a default template which will be used unless you pass the config option template: false.

If you pass an empty string or do not include anything, it will render using the default-template.jade in this repository.

The jade template will receive the following locals:

	var jadeLocals = {
      structure:  organizedByClass,
      comments:   thisClassDocs,
      className:  classKey,
      link: classCommentLink,
	  files: allFileLinks,
	  basePath: basePath,
	  filenameOut: filenameOut
    };

Default template

default jade jsdoxy template

Markdown files

Any markdown files with the extension .md will be turned into HTML files and rendered with the jade template.

Overriding the default template CSS classes

The following CSS classes are exposed:

  • .docs
  • .docs--sidebar
  • .docs--main
  • .docs--subtitle
  • .docs--title

License

(c) 2014 - 2015 Jeff H. Parrish

[email protected]

MIT

Forked from tj/dox