lee-dohm / endokken Goto Github PK

Converts AtomDoc to lovely HTML documentation.

Home Page: https://www.npmjs.com/package/endokken

License: MIT License

CoffeeScript 65.60% JavaScript 0.35% HTML 5.13% CSS 28.92%

endokken's Introduction

Endokken

Generates HTML documentation for your Atom package from AtomDoc comments in your code and your GitHub project's own Markdown files.

Command-Line Interface

You can simply run the endokken command from the root directory of your Atom package and it will generate HTML documentation in the ./docs directory.

$ endokken

Endokken also supports the following command-line options:

--extension [EXT] — Adds the given extension to all generated documentation files. Defaults to no extension for REST-like purity.
--metadata [FILENAME] — Dumps the AtomDoc metadata to the file name you provide or api.json if no filename is given.
--title [TITLE] — Title of index page, default is name of current directory.
--version — Displays the version.
--help — Displays command-line help.

Acknowledgements

Endokken was originally envisioned as YARD for Atom packages. As such, Endokken owes a lot of its inspiration and ideas to YARD and its author Loren Segal.

Copyright

endokken's People

Contributors

Stargazers

Watchers

Forkers

abe33 jessegrosjean jysperm klorenz

endokken's Issues

Resolve references when generating file pages:

In FilePage>Render:

@markdownify(@resolveReferences(fs.readFileSync(@filePath).toString()))

Extract references to common directories into constants

Dump both metadata types on --metadata parameter

Convert to running CoffeeScript without pre-compilation

Like in Donna:

https://github.com/atom/donna/blob/master/bin/donna

Add hover tooltips to perma- and code-links

Null method section should always be output first

I'm sure all the issues that I raise here are pretty easily solvable with some custom styling/tweaking, but I wonder if the defaults should change. I really like the way that the Atom.io generated API docs omit much of the boiler plate that most documentation tools generate. I think it would make sense for Atom package generated docs to have that same feel.

As some examples of boiler plate included in endokken but not in Atom api docs:

Ommit the "Class:" before the generated classname
Ommit the table of class info after classname (Class Name, Superclass, File)
Ommit "Description" heading before class description
Make each class description "collapsed" by default so you just see the method signature. Click to expand... again like Atom.io API docs.

Thanks,
Jesse

Add .yardopts-style configuration file

Add command-line switch for outputting the metadata

Should not resolve things that look like doc references if they are in backticks

See the Resolver class documentation header.

Error when generating documentation for the minimap package

I'm not sure what trigger this error as I was just trying your package for the first time. Maybe it's something related to the various mixins used in the package?

/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:363
        moduleName = exp.args[0].base.value;
                                     ^
TypeError: Cannot read property 'value' of undefined
  at Metadata.module.exports.Metadata.evalCall (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:282:36)
  at Metadata.module.exports.Metadata.eval (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:23:5)
  at Metadata.module.exports.Metadata.visitAssign (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:36:13)
  at Metadata.module.exports.Metadata.visit (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:21:5)
  at /Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:18:42
  at /Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/coffee-script/lib/coffee-script/nodes.js:210:17
  at Block.exports.Base.Base.eachChild (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/coffee-script/lib/coffee-script/nodes.js:198:17)
  at Block.exports.Base.Base.traverseChildren (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/coffee-script/lib/coffee-script/nodes.js:208:19)
  at Metadata.module.exports.Metadata.generate (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/metadata.coffee:18:11)
  at generateMetadataSlug (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/donna.coffee:121:14)
  at Object.generateMetadata (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/node_modules/donna/src/donna.coffee:75:24)
  at Cli.generateMetadata (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/src/cli.coffee:79:23)
  at Cli.run (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/src/cli.coffee:30:6)
  at Object.<anonymous> (/Users/cedric/.nvm/v0.10.21/lib/node_modules/endokken/bin/endokken:7:5)
  at Module._compile (module.js:456:26)
  at Object.Module._extensions..js (module.js:474:10)
  at Module.load (module.js:356:32)
  at Function.Module._load (module.js:312:12)
  at Function.Module.runMain (module.js:497:10)
  at startup (node.js:119:16)
  at node.js:901:3

Configuration:

OSX 10.10.2
Node 0.10.21

Add support for nested arguments

Add support for keymaps

Treat Superclass field on class page as a doc reference

... and resolve it:

Add more logging control

Add support for examples sections

Add support for commands

This might be a little harder than the keymaps and menus, since it will require parsing of the source code.

Add emoji support in all markdown sections

Add header to file page if one doesn't already exist

Otherwise the alignment is off:

Add support for styles/classes?

Would it be useful to document the "public" stylesheet classes that an Atom package provides? For instance I have a public stylesheet class on my indentation indicator package that allows the user to restyle the indicator. It might be helpful for that kind of thing to show up in the Endokken documentation.

Private
Internal
Experimental

Add support for optional parameters

Add animation when navigating to ID that makes ID glow for a second

For example, if a page is launched with Foo#instance-bar then the ::bar header and border should glow yellow for a half-second then fade to blue.