Skip to content
This repository

Simple, open-ended JavaScript source documentation system based on markdown. joDoc rev 1.0.1 is available. Check Wiki page for some examples.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 samples
Octocat-spinner-32 .gitignore
Octocat-spinner-32 ABOUT.mdown
Octocat-spinner-32 LICENSE.mdown
Octocat-spinner-32 README.mdown
Octocat-spinner-32 TEMPLATE.mdown
Octocat-spinner-32 TOC.mdown
Octocat-spinner-32 jodoc
README.mdown

joDoc

joDoc is a plain text code documentation scheme for JavaScript. It was created out of frustration felt working with various documentation systems available. joDoc does not attempt to perform any special automation other than generating links, table of contents, an index, and of course rendered HTML for your documentation.

Source code formatting

This is a simple example of what you can do in your source documentation. This is all free-form markdown text.

/**
    myClass
    =======

    This is my class. It rocks, and this is its _description_, which also
    rocks.

    Extends
    -------

    - someOtherClass

    Methods
    -------

    - setName(name)

      Where `name` is a `String`.

    Use
    ---
        // here is some sample code which shows how to use this class
        var x = new myClass(name);

    > Note: use of the `name` reserved word is probaly a bad idea.
*/

Comment placement

You can put your comments for your code either:

  1. in your source code (anywhere and in as many pieces as you want) denoted with /** ... */ multiline-comment blocks

  2. separate markdown (*.mdown) files, probably (tho not necessarily) named to match your JavaScript files

Can't get much more flexible than that.

Requirements

  1. perl 5.8 or greater (YMMV with older perl versions)
  2. Markdown.pl (or compatible parser)
  3. SmartyPants.pl (optional)

Windows users should get some suggestions for installing ActiveState or cygwin

Use

jodoc [--output path] [--title string] [--toc file] [--template file] [--markdown file] [-s] [--smartypants file] [filespec]
  • --output path

    specify a path to where you want doc files placed

  • --toc file

    joDoc will work with a table of contents structure defined in a markdown file. Your TOC file can be completely manual, just a list of atuo-linked terms (or markdown or even HTML style links), but joDoc will do do more if you want it. For example:

      Developer Guide
      ---------------
    
      - {ABOUT.mdown}
      - {README.mdown}
      - {docs/}
      - {LICENSE.mdown}
    
      API Reference
      -------------
    
      ### Core
      - {js/core}
    
      ### Data
      - {js/data}
    
      ### User Interface
      - {js/ui}
    

    You can put a file path inside the {} pairs, and joDoc will attempt to find and sort all the headers from the files which match that pattern.

NOTE: the TOC is not a replacement for the filespec in the command line. You need to make sure to tell joDoc what directorie(s) to parse. The TOC is a semi-automated document which can be useful but is not required.

  • --markdown file

    tells joDoc to use a specific markdown parser.

  • --title string

    is an optional title which will appear on your HTML output.

  • --template file

    tells joDoc to use a custom HTML file as a template, a simple example:

      <html><head><title>$title</title></head>
      <body>$body</body></html>
    
  • --smartypants

    tells joDoc to use a specific smartypants prettifier.

  • -s

    tells joDoc to filter output through SmartyPants.

  • tidy

    tells joDoc to use the HTMLTidy prettifier.

  • htmltidy string

    tells joDoc to use a specific HTMLTidy compatible prettifier

  • filespec

    is one or more files to parse. Directories will be recursively handled.

    Note: No support for STDIN input at the moment. Use named pipes for now. Also, block devices like /dev/random are totally untested.

Examples

Simple case:

jodoc

By default, joDoc will start in the current directory and recursively look for *.mdown, .*.js and *.css files to build documentation. Unless directed otherwise, joDoc will print a unified HTML file on standard out with all the documentation output, and an index of all <h1> tags.

Specifying an output base directory:

jodoc --output /var/www/html/docs

Specifying files to parse:

jodoc ABOUT.mdown *.js *.css

Defining a table of contents structure:

jodoc --toc ~/release.toc

Building joDoc's documentation with joDoc:

jodoc --output html -s --toc samples/TOC_SAMPLE.mdown *.mdown
cp samples/css/* html/
cp samples/index.html html/

Note that the css and index.html step is specific to this documentation set; it is not necessarily required for the docs in your project.

Something went wrong with that request. Please try again.