Convert q documentation comments to Markdown documents
Project description
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
- 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 - The first docomment presents a high-level summary of what the entity does. It may span multiple lines.
- The following tags are supported (
<>
represents placeholder,[]
represents optional element,{}
are verbatim to put an element in a group regardless of whitespace):@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.@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
.@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.@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.@signal {<error>} [description]
: errors that may be signaled.@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.@see {<name>} <description>
: Entry for reference. Preferably<name>
is a link either via@link
or a usual Markdown link.<description>
supports Markdown syntax.@note <description>
: A note about the object being documented.@deprecated
: Mark the entity deprecated. It should appear following the docomment prompt.@link <name>
: Add a link to a name which is documented in the same project.
- All occurrences of
<description>
above support Markdown syntax. - 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
- Atom datatypes such as
boolean
andguid
, as shown in Datatypes on the reference page of q. number
: alias to eithershort
,int
,long
,real
orfloat
.hsym
: a subclass ofsymbol
for file or process symbolsdict
ordict(symbol->int)
: a dictionary, with optionally the datatypes of its key and value.table
ortable([c1:date]c2:symbol)
: a table, with optionally column names and datatypesfn
orfn(date;long)->date
: a function, with optionally the datatypes of its parameters and return value.
Compound Types
- Vector of atom datatypes, e.g.
boolean[]
. list
orlist(symbol;long)
: generic list, with optionally datatypes of its elements.string
: an alias tochar[]
.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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
qdoc2md-0.6.tar.gz
(12.9 kB
view hashes)
Built Distribution
qdoc2md-0.6-py3-none-any.whl
(7.2 kB
view hashes)