| Name | qdoc2md JSON |
| Version |
0.6
JSON |
| download |
| home_page | None |
| Summary | Convert q documentation comments to Markdown documents |
| upload_time | 2024-11-05 16:42:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
kdb
markdown
qdoc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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`.
```bash
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
1. The first docomment presents a high-level summary of what the entity does. It may span multiple lines.
1. 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.
1. `@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`.
1. `@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.
1. `@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.
1. `@signal {<error>} [description]`: errors that may be signaled.
1. `@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.
1. `@see {<name>} <description>`: Entry for reference. Preferably `<name>` is a link either via `@link` or a usual Markdown link. `<description>` supports Markdown syntax.
1. `@note <description>`: A note about the object being documented.
1. `@deprecated`: Mark the entity deprecated. It should appear following the docomment prompt.
1. `@link <name>`: Add a link to a name which is documented in the same project.
1. All occurrences of `<description>` above support Markdown syntax.
1. 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](https://code.kx.com/q/ref/#datatypes) on the reference page of q.
1. `number`: alias to either `short`, `int`, `long`, `real` or `float`.
1. `hsym`: a subclass of `symbol` for file or process symbols
1. `dict` or `dict(symbol->int)`: a dictionary, with optionally the datatypes of its key and value.
1. `table` or `table([c1:date]c2:symbol)`: a table, with optionally column names and datatypes
1. `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[]`.
1. `list` or `list(symbol;long)`: generic list, with optionally datatypes of its elements.
1. `string`: an alias to `char[]`.
1. `any`: any datatype.
# Example
See [sample.q](resources/sample.q) for a sample q script with the designated docomments, and [sample.md](resources/docs/sample.md) for the generated Markdown document. A static site can be built on top of the generated doc via [mkdocs](https://www.mkdocs.org/), e.g. `cd resources && mkdocs serve`
Raw data
{
"_id": null,
"home_page": null,
"name": "qdoc2md",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "kdb, markdown, qdoc",
"author": null,
"author_email": "Darren Sun <darren@darrensun.pro>",
"download_url": "https://files.pythonhosted.org/packages/29/cb/b4498090b3ff8cf8356b908597219ffbb9071c8a358a1fb8cfa35781b2c7/qdoc2md-0.6.tar.gz",
"platform": null,
"description": "# qdoc2md\n\nThis tool converts q documentation comments conforming to the specifications below to Markdown documents.\n\n## Getting Started\n\nInstall the package via `pip install qdoc2md` and run the following command to generate docs saved in `docs`.\n\n```bash\nqdoc2md --src <your_q_src> --target <output_dir>\n```\n\n## Specifications of Documentation Comments\n\n1. 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\n1. The first docomment presents a high-level summary of what the entity does. It may span multiple lines. \n1. The following tags are supported (`<>` represents placeholder, `[]` represents optional element, `{}` are verbatim to put an element in a group regardless of whitespace):\n 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.\n 1. `@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`.\n 1. `@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.\n 1. `@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.\n 1. `@signal {<error>} [description]`: errors that may be signaled.\n 1. `@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.\n 1. `@see {<name>} <description>`: Entry for reference. Preferably `<name>` is a link either via `@link` or a usual Markdown link. `<description>` supports Markdown syntax.\n 1. `@note <description>`: A note about the object being documented. \n 1. `@deprecated`: Mark the entity deprecated. It should appear following the docomment prompt.\n 1. `@link <name>`: Add a link to a name which is documented in the same project.\n1. All occurrences of `<description>` above support Markdown syntax.\n1. Use a datatype described below for `<datatype>`.\n\n## Datatypes\n\nDatatype is free-form text but it is suggested to use the following for consistency.\n\n### Basic Types\n\n1. Atom datatypes such as `boolean` and `guid`, as shown in [Datatypes](https://code.kx.com/q/ref/#datatypes) on the reference page of q.\n1. `number`: alias to either `short`, `int`, `long`, `real` or `float`.\n1. `hsym`: a subclass of `symbol` for file or process symbols\n1. `dict` or `dict(symbol->int)`: a dictionary, with optionally the datatypes of its key and value.\n1. `table` or `table([c1:date]c2:symbol)`: a table, with optionally column names and datatypes\n1. `fn` or `fn(date;long)->date`: a function, with optionally the datatypes of its parameters and return value.\n\n### Compound Types\n\n1. Vector of atom datatypes, e.g. `boolean[]`.\n1. `list` or `list(symbol;long)`: generic list, with optionally datatypes of its elements.\n1. `string`: an alias to `char[]`.\n1. `any`: any datatype.\n\n# Example\n\nSee [sample.q](resources/sample.q) for a sample q script with the designated docomments, and [sample.md](resources/docs/sample.md) for the generated Markdown document. A static site can be built on top of the generated doc via [mkdocs](https://www.mkdocs.org/), e.g. `cd resources && mkdocs serve`",
"bugtrack_url": null,
"license": null,
"summary": "Convert q documentation comments to Markdown documents",
"version": "0.6",
"project_urls": {
"Homepage": "https://github.com/darrenwsun/qdoc2md",
"Issues": "https://github.com/darrenwsun/qdoc2md/issues"
},
"split_keywords": [
"kdb",
" markdown",
" qdoc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3bd13c72dd3c69a453e42db940f042b9945f1dc938e02bda3f458f2d4c1b390e",
"md5": "c25edd98f59d2f12c500702ebe51e432",
"sha256": "e23f1e66964eab22d43df4ce4f703279a06c81a5c614473167dd3ebf9c7fad5e"
},
"downloads": -1,
"filename": "qdoc2md-0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c25edd98f59d2f12c500702ebe51e432",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7237,
"upload_time": "2024-11-05T16:42:27",
"upload_time_iso_8601": "2024-11-05T16:42:27.636641Z",
"url": "https://files.pythonhosted.org/packages/3b/d1/3c72dd3c69a453e42db940f042b9945f1dc938e02bda3f458f2d4c1b390e/qdoc2md-0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "29cbb4498090b3ff8cf8356b908597219ffbb9071c8a358a1fb8cfa35781b2c7",
"md5": "a2c6c5e55f224219a07dac5a244dd79e",
"sha256": "ea3f3b9afbbd3af916a176bd41892155c658bd25aa01f7d409a9ba6dcda49012"
},
"downloads": -1,
"filename": "qdoc2md-0.6.tar.gz",
"has_sig": false,
"md5_digest": "a2c6c5e55f224219a07dac5a244dd79e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12950,
"upload_time": "2024-11-05T16:42:28",
"upload_time_iso_8601": "2024-11-05T16:42:28.669934Z",
"url": "https://files.pythonhosted.org/packages/29/cb/b4498090b3ff8cf8356b908597219ffbb9071c8a358a1fb8cfa35781b2c7/qdoc2md-0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-05 16:42:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "darrenwsun",
"github_project": "qdoc2md",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "qdoc2md"
}
