jodoc-js
A nodejs port of joDoc
Features
- Automatic conversion of markdown commented javascript code
- Self-linking documenatation
- A quick and easy table of contents system
- JSON configuration coming soon __Note: not soon enough it seems __
Usage
node jodoc-js <bunch of files>
- .css, .js files are parsed for markdown comments
- .mdown, .markdown, or .md files can use freeform markdown
- Recurses on folders
- Has some options
- output: output folder name, creates individual files for each parsed file instead of one combined output file
- no-index: don't make an _index.html for the resulting output folder
- toc: Table of Contents template to fill in to contents.html
- title: file in the
<title>tag with the provided string - template: use provided file as an html template
- Use
$titlefor where the title goes - Use
$bodyin the<body>tag, or wherever
- Use
Example using provided Samples
node jodoc-js --toc samples/TOC\_SAMPLE.mdown --template samples/template.html --output dist src/file1.js src/file2.js doc/main.mdown doc/styleguilde.mdown
Status
- Breaks from joDoc
- New syntax for autolinking:
[<h1name>].- Better control over linking
- Github style markdown
- I like it better, that's why
- New syntax for autolinking:
New stuff, or "Docs Gone Wild!"
-
Everything in jodoc-lib intended to be stateless.
-
jodoc.js divorced from jodoc-lib, jodoc.js intended to be a simple client
-
Don't like jodoc.js? Write your own! Lemme know if jodoc-lib needs better docs.
-
Don't like showdown? Use your own! Maintaining a process spawner for the sample client was too much.
-
Don't like the TOC format? Write your own! Supply a regex to toclinker and it parses that input instead!
Planned:
Adding some new features to the jodoc spec, including easier auto-linking between documentation sets. Basically, to make it easier to "roll up" docs from one or more code bases. Consider the following case:
- docs from JS lib from vendor A
- docs from JS lib from vendor B
- project-specific docs from application level code
- coding standards and other esoteric docs
Basically, working on an optional way to easily unite stuff like this into a single TOC and have auto-linking applied throughout.
Some considerations:
-
there may be more than one section with the same name; so a disambiguation scheme for links that have more than one place to go
-
some doc sets can and should put more levels than H1 in their TOC, this is more the case for esoteric docs than code docs
-
leaning on the new JSON config file notion to fuel this