Desc
Installation
Run
Tags
Tag chaining
Rules
Todo
Resources
A tool powered by Sphinx for documenting the q code with some predefined tags generating HTML/wiki-style documents.
For more information and examples please visit the sphinx[Q] wiki.
Sphinx is written in Python and supports both Python 3.3+ & Python 2.7, You must have Python 3 or Python 2.7 installed. However the later is recommended.
There are multiple ways to get the sphinx installed on the machine, here is the full wiki on how to get it installed.
A quick way to get the Sphinx installed if you already have Python installed using the PyPI (pip)
C:\> pip install -U sphinx
c:\Code\Github\sphinxQ>q run.q
Here are some tags that can be used in the code as comments and it will be automatically parsed and included in the documents.
- @name
- @package
- @desc
- @function
- @code
- @eval
- @param
- @return
- @header
- @row
- @todo
- @schema
- @toggle
- @bullet
- @error
- @see
- @tags
@version
Applying the formatting of multiple tags over the same content. Tags can be chained using a - e.g. @toggle-code means apply the @toggle formatting over the output of @code.
- Search for all the lines containing
/#(which also includes/#.for multiline comments) - Except for the first delimiter
/#appearance, all subsequent/#will be treated as@descor paragraph. - Search the lines which contain tags prefixed by
@(e.g.@function,@param) - For few tags (
package,function,schemaetc.), the immediate word after the tag will be treated as the tag name and rest will be treated as a description. - In case
@packageor@nameis defined multiple times, the first entry will be used for meta uses (labelling the links, rst naming, document title etc.) - Now process each tag along with the content using the
ReSThelper functions.
- Multiline comments support (
/#.) - Enable
@bullettag show/hide(toggle) code/content feature.- Handle scenarios when a file with same name present in different folders/package.
- Library cyclic dependency
- Handle multiline code scenario