Skip to content
/ sphinxQ Public

A tool powered by Sphinx for documenting the q code with some predefined tags generating HTML/wiki-style documents.

License

Notifications You must be signed in to change notification settings

aa1024/sphinxQ

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Table of Contents

Desc
Installation
Run
Tags
Tag chaining
Rules
Todo
Resources


sphinx[Q]

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

About

A tool powered by Sphinx for documenting the q code with some predefined tags generating HTML/wiki-style documents.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published