SCDoc manages the SuperCollider documentation system.
It uses parses help files written in SCDoc markup language and renders them as human-readable documents.
A guide to writing help can be found here: Writing Help.
Index all documents and undocumented classes on the system, putting them in the SCDoc.documents dictionary. If run inside a Routine, this method will yield occasionally.
Run this method if you added a new document and want to see the changes without restarting SuperCollider.
| clearCache |
If true, force re-render of files even if the schelp source file is not newer than the destination. |
This will take a couple of seconds, and will be done automatically once before any help can be viewed. You might consider putting this in your startup.scd file to avoid getting this delay later when you decide to view a helpfile.
The dictionary of indexed documents. They keys are the path relative to the Help folder and without extension, like Classes/SinOsc or Reference/SCDocSyntax. The values are instances of SCDocEntry
A Boolean indicating if SCDoc.indexAllDocuments was called in this session yet.
get/set the system-wide directory of help sourcefiles. Defaults to Platform.classLibraryDir.dirname +/+ "HelpSource" and should typically not be changed by the user.
get the list of HelpSource folders, including extensions and quarks (unless they are excluded from library compilation, e.g. by LanguageConfig: *excludeDefaultPaths)
This searches recursively for all folders named "HelpSource" under LanguageConfig: *includePaths, as well as including the system-wide helpSourceDir. Unless LanguageConfig: *excludeDefaultPaths is on, Platform.userExtensionDir and Platform.systemExtensionDir are searched too.
Find help for a given string. Tries to be smart.
the URL for help on given string
Verbosity level. 0 is silent.
The default renderer, defaults to SCDocHTMLRenderer
get/set the user help target directory. Defaults to Platform.userAppSupportDir +/+ "Help" and should typically not be changed by the user.
Parse only the stuff needed for metadata.
| dir |
Base HelpSource directory. |
| path |
Path relative above dir. |
An SCDocNode tree
Parse a file without header, for merging of document additions
| path |
Full path to .ext.schelp file |
An SCDocNode tree
Parse the files associated with an SCDocEntry, including any document additions (*.ext.schelp)
| doc |
The SCDocEntry to parse. |
An SCDocNode tree
Render all help-files. Useful mainly if you want to render all help to put online or similar.
| includeExtensions |
If false, skip quarks, plugins and other extensions. |
Prepare help for the given URL by checking if the file needs rendering from schelp source, or some other action needs to be done. Used as a wrapper to get on-the-fly rendering and processing of help files.
| url |
The url to prepare. If this is not a local file inside *helpTargetDir then it will just pass through the url directly. |
the URL or nil if file not found.
Extract the SCDocNode tree for the specified method documentation.
| classname |
Name of class |
| methodname |
Name of method, prefixed with |
An SCDocNode tree
Create a schelp template for specified class.
| doc |
The SCDocEntry for the undocumented class. |
Returns the template string.
The SCDoc parser outputs a tree of SCDocNodes
The nodes reflects the tags in the input, but it's not a one-to-one correspondence. A more detailed structure is added in the node tree, for easier rendering.
Example:
DOCUMENT
"SinOsc""Interpolating sine wavetable oscillator""Classes/FSinOsc""Classes/SinOscFB""UGens>Generators>Deterministic""UGens>Oscillators""A paragraph with ""Classes/Osc##a link"" to another document.""Another paragraph with ""strong words"" in it.""Some text...""ar""kr""Some text...""freq""Frequency in hertz""phase""Phase modulation""Here are some examples:""{ SinOsc.ar(200, 0, 0.5) }.play;
// modulate freq
{ SinOsc.ar(XLine.kr(2000, 200), 0, 0.5) }.play;
// modulate freq
{ SinOsc.ar(SinOsc.ar(XLine.kr(1, 1000, 9), 0, 200, 800), 0, 0.25) }.play;
// modulate phase
{ SinOsc.ar(800, SinOsc.ar(XLine.kr(1, 1000, 9), 0, 2pi), 0.25) }.play;""Another section""Some text..."