icondoc is a documentation tool converting Icon file comments into html documentation: it is inspired by Ruby's rdoc.

Features

• documents individual files from one or more files
• produces an integrated set of html pages with sidebar to navigate to each file
• optional title-page documentation
• top-level header comments, with links, globals, procedures and records documented
• comments can use the following syntax:
  • comments starting '#>' are placed at the top of the output documentation
  • blank lines signal a paragraph break
  • comment lines start '# ' and then
    • lines continuing with ' ' (two spaces) are part of a pre-block
    • lines continuing with '. ' are part of an enumerated list
    • lines continuing with '* ' or '- ' are part of an itemised list
    • lines continuing with '[word] sentence' are description lists
• items with a comment including a line with "# NODOC" are not output

Requirements

• pcl libraries

Install

• download the latest release of icon-tools
• compile the code in "icondoc" with "icont" (tested using Icon 9.5.1), e.g.:

  > icont icondoc.icn
  

• place "icondoc.icx" somewhere on your PATH

Basic Use

To document the icondoc file, call:

> icondoc icondoc.icn

• Copy the example style sheet from "icondoc/style.css" to "doc/style.css".
• Open "doc/index.html" in a web browser.

For more options:

> icondoc -h
icondoc:
Extracts documentation from code in file(s)
writing html files into destination_folder (default 'doc/').
(Ignores files named NAME_test.icn, unless using --include-tests.)

-h --help                : displays help message
-v --version             : show version
-d --destination folder  : destination folder, defaults to 'doc/'
-t --title-page filename : file of html to use in title page
-r --read-files          : read file list from stdin, e.g. piped from another source
--include-tests          : includes _test.icn files

Filenames can be listed on the command-line. However, on Windows, CMD does not expand wildcards into multiple files. Therefore, the flag "-r" makes icondoc read the filenames from stdin, enabling you to pipe the filenames to the program:

> dir /b *.icn | icondoc -r

Limitations/Plans

• bold/italic/links should be recognised in comments