qdoc2md 0.5.5

Convert q documentation comments to Markdown documents

qdoc2md

This tool converts q documentation comments conforming to the specifications below to Markdown documents.

Getting Started

Install the package via pip install qdoc2md and run the following command to generate docs saved in docs.

qdoc2md --src <your_q_src> --target <output_dir>

Specifications of Documentation Comments

1. Docomments start with /// (referred to as "docomment prompt" below) with whitespaces on both ends of the line ignored, and they are placed in a consecutive block above the entity (function or variable) to be documented
2. The first docomment presents a high-level summary of what the entity does. It may span multiple lines.
3. The following tags are supported (<> represents placeholder, [] represents optional element, {} are verbatim to put an element in a group regardless of whitespace):
   1. @title <title>: A word or very short phrase about the script. This is preferably put at the top of the script. In its absence, the name of the script is used as the title.
   2. @overview <description>: An high-level summary of what the script does, written in Markdown. This is preferably put at the top of the script, following @title.
   3. @param <name> [@atomic] [{datatype}] [description]: Description of a parameter of a function, including its name, optional flag for atomic behavior, optional datatype, and more details such as what it represents.
   4. @returns [<name>] [{<datatype>}] [description]: Description of return value of a function, including its optional name, optional datatype, and more details such as what it represents.
   5. @signal {<error>} [description]: errors that may be signaled.
   6. @example: Example usage of a function. It should appear following the docomment prompt, and the example starts from the next line until the presence of another tag.
   7. @see {<name>} <description>: Entry for reference. Preferably <name> is a link either via @link or a usual Markdown link. <description> supports Markdown syntax.
   8. @deprecated: Mark the entity deprecated. It should appear following the docomment prompt.
   9. @link <name>: Add a link to a name which is documented in the same project.
4. All occurrences of <description> above support Markdown syntax.
5. Use a datatype described below for <datatype>.

Datatypes

Datatype is free-form text but it is suggested to use the following for consistency.

Basic Types

1. Atom datatypes such as boolean and guid, as shown in Datatypes on the reference page of q.
2. number: alias to either short, int, long, real or float.
3. hsym: a subclass of symbol for file or process symbols
4. dict or dict(symbol->int): a dictionary, with optionally the datatypes of its key and value.
5. table or table([c1:date]c2:symbol): a table, with optionally column names and datatypes
6. fn or fn(date;long)->date: a function, with optionally the datatypes of its parameters and return value.

Compound Types

1. Vector of atom datatypes, e.g. boolean[].
2. list or list(symbol;long): generic list, with optionally datatypes of its elements.
3. string: an alias to char[].
4. any: any datatype.

Example

See sample.q for a sample q script with the designated docomments, and sample.md for the generated Markdown document. A static site can be built on top of the generated doc via mkdocs, e.g. cd resources && mkdocs serve