Skip to content

dfreedm/jodoc-js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

67 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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 $title for where the title goes
      • Use $body in the <body> tag, or wherever

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 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