GitHub

Table of Contents

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.

Installation

Windows

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

Run

c:\Code\Github\sphinxQ>q run.q

Tags

Here are some tags that can be used in the code as comments and it will be automatically parsed and included in the documents.

Tag chaining

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.

Rules

  • Search for all the lines containing /# (which also includes /#. for multiline comments)
  • Except for the first delimiter /# appearance, all subsequent /# will be treated as @desc or paragraph.
  • Search the lines which contain tags prefixed by @ (e.g. @function, @param)
  • For few tags (package, function, schema etc.), the immediate word after the tag will be treated as the tag name and rest will be treated as a description.
  • In case @package or @name is 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 ReST helper functions.

TODO

  • Multiline comments support (/#.)
  • Enable @bullet tag
  • 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

Resources

Read the original on github.com ↗