Skip to main content

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

  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. @note <description>: A note about the object being documented.
    9. @deprecated: Mark the entity deprecated. It should appear following the docomment prompt.
    10. @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

Project details


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

Uploaded Source

Built Distribution

qdoc2md-0.6-py3-none-any.whl (7.2 kB view details)

Uploaded Python 3

File details

Details for the file qdoc2md-0.6.tar.gz.

File metadata

  • Download URL: qdoc2md-0.6.tar.gz
  • Upload date:
  • Size: 12.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-httpx/0.27.0

File hashes

Hashes for qdoc2md-0.6.tar.gz
Algorithm Hash digest
SHA256 ea3f3b9afbbd3af916a176bd41892155c658bd25aa01f7d409a9ba6dcda49012
MD5 a2c6c5e55f224219a07dac5a244dd79e
BLAKE2b-256 29cbb4498090b3ff8cf8356b908597219ffbb9071c8a358a1fb8cfa35781b2c7

See more details on using hashes here.

File details

Details for the file qdoc2md-0.6-py3-none-any.whl.

File metadata

  • Download URL: qdoc2md-0.6-py3-none-any.whl
  • Upload date:
  • Size: 7.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-httpx/0.27.0

File hashes

Hashes for qdoc2md-0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 e23f1e66964eab22d43df4ce4f703279a06c81a5c614473167dd3ebf9c7fad5e
MD5 c25edd98f59d2f12c500702ebe51e432
BLAKE2b-256 3bd13c72dd3c69a453e42db940f042b9945f1dc938e02bda3f458f2d4c1b390e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page