237 lines
7.8 KiB
Text
237 lines
7.8 KiB
Text
|
class:: SCDoc
|
||
|
|
summary:: Help system main class
|
||
|
|
categories:: HelpSystem
|
||
|
|
related:: Reference/SCDocSyntax, Guides/WritingHelp, Classes/SCDocHTMLRenderer, Classes/SCDocNode, Classes/SCDocEntry
|
||
|
|
|
||
|
|
DESCRIPTION::
|
||
|
|
SCDoc manages the SuperCollider documentation system.
|
||
|
|
|
||
|
|
It uses parses help files written in link::Reference/SCDocSyntax##SCDoc markup language:: and renders them as human-readable documents.
|
||
|
|
|
||
|
|
A guide to writing help can be found here: link::Guides/WritingHelp::.
|
||
|
|
|
||
|
|
CLASSMETHODS::
|
||
|
|
|
||
|
|
subsection:: Document index
|
||
|
|
|
||
|
|
method:: indexAllDocuments
|
||
|
|
Index all documents and undocumented classes on the system, putting them in the code::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.
|
||
|
|
|
||
|
|
argument:: clearCache
|
||
|
|
If true, force re-render of files even if the schelp source file is not newer than the destination.
|
||
|
|
|
||
|
|
discussion::
|
||
|
|
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.
|
||
|
|
|
||
|
|
method:: documents
|
||
|
|
The dictionary of indexed documents. They keys are the path relative to the Help folder and without extension, like teletype::Classes/SinOsc:: or teletype::Reference/SCDocSyntax::. The values are instances of link::Classes/SCDocEntry::
|
||
|
|
|
||
|
|
method:: didIndexDocuments
|
||
|
|
A Boolean indicating if code::SCDoc.indexAllDocuments:: was called in this session yet.
|
||
|
|
|
||
|
|
method:: helpSourceDir
|
||
|
|
get/set the system-wide directory of help sourcefiles. Defaults to code::Platform.classLibraryDir.dirname +/+ "HelpSource":: and should typically not be changed by the user.
|
||
|
|
|
||
|
|
method:: helpSourceDirs
|
||
|
|
get the list of HelpSource folders, including extensions and quarks.
|
||
|
|
discussion::
|
||
|
|
This searches recursively for all folders named "HelpSource" under code::Platform.userExtensionDir:: and code::Platform.systemExtensionDir:: as well as including the system-wide code::helpSourceDir::
|
||
|
|
|
||
|
|
method:: findHelpFile
|
||
|
|
Find help for a given string. Tries to be smart.
|
||
|
|
returns:: the URL for help on given string
|
||
|
|
|
||
|
|
method:: verbosity
|
||
|
|
Verbosity level. 0 is silent.
|
||
|
|
|
||
|
|
subsection:: Parsing and Rendering
|
||
|
|
|
||
|
|
private:: checkVersion, exportDocMapJS, handleCopyMethods, postMsg, prParseFile, renderUndocClass
|
||
|
|
|
||
|
|
method:: renderer
|
||
|
|
The default renderer, defaults to link::Classes/SCDocHTMLRenderer::
|
||
|
|
|
||
|
|
method:: helpTargetDir
|
||
|
|
get/set the user help target directory. Defaults to code::Platform.userAppSupportDir +/+ "Help":: and should typically not be changed by the user.
|
||
|
|
|
||
|
|
method:: parseFileFull
|
||
|
|
Parse file.
|
||
|
|
argument::
|
||
|
|
Full path to .schelp file
|
||
|
|
returns::
|
||
|
|
An link::Classes/SCDocNode:: tree
|
||
|
|
|
||
|
|
method:: parseFileMetaData
|
||
|
|
Parse only the stuff needed for metadata.
|
||
|
|
argument::
|
||
|
|
Base HelpSource directory.
|
||
|
|
argument::
|
||
|
|
Path relative above dir.
|
||
|
|
returns::
|
||
|
|
An link::Classes/SCDocNode:: tree
|
||
|
|
|
||
|
|
method:: parseFilePartial
|
||
|
|
Parse a file without header, for merging of document additions
|
||
|
|
argument::
|
||
|
|
Full path to .ext.schelp file
|
||
|
|
returns::
|
||
|
|
An link::Classes/SCDocNode:: tree
|
||
|
|
|
||
|
|
method:: parseDoc
|
||
|
|
Parse the files associated with an link::Classes/SCDocEntry::, including any document additions (teletype::*.ext.schelp::)
|
||
|
|
argument:: doc
|
||
|
|
The link::Classes/SCDocEntry:: to parse.
|
||
|
|
returns::
|
||
|
|
An link::Classes/SCDocNode:: tree
|
||
|
|
|
||
|
|
method:: parseAndRender
|
||
|
|
Parse and render a specific document.
|
||
|
|
argument:: doc
|
||
|
|
The link::Classes/SCDocEntry:: to parse and render.
|
||
|
|
|
||
|
|
method:: renderAll
|
||
|
|
Render all help-files. Useful mainly if you want to render all help to put online or similar.
|
||
|
|
argument:: includeExtensions
|
||
|
|
If false, skip quarks, plugins and other extensions.
|
||
|
|
|
||
|
|
method:: prepareHelpForURL
|
||
|
|
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.
|
||
|
|
argument:: url
|
||
|
|
The url to prepare. If this is not a local file inside link::#*helpTargetDir:: then it will just pass through the url directly.
|
||
|
|
returns:: the URL or nil if file not found.
|
||
|
|
|
||
|
|
subsection:: Utilities
|
||
|
|
|
||
|
|
method:: getMethodDoc
|
||
|
|
Extract the link::Classes/SCDocNode:: tree for the specified method documentation.
|
||
|
|
argument::
|
||
|
|
Name of class
|
||
|
|
argument::
|
||
|
|
Name of method, prefixed with teletype::*:: for classmethods and teletype::-:: for instancemethods.
|
||
|
|
returns::
|
||
|
|
An link::Classes/SCDocNode:: tree
|
||
|
|
|
||
|
|
method:: makeClassTemplate
|
||
|
|
Create a schelp template for specified class.
|
||
|
|
argument:: doc
|
||
|
|
The link::Classes/SCDocEntry:: for the undocumented class.
|
||
|
|
returns::
|
||
|
|
Returns the template string.
|
||
|
|
|
||
|
|
method:: classHasArKrIr
|
||
|
|
argument:: c
|
||
|
|
The link::Classes/Class:: to check.
|
||
|
|
Returns:: code::true:: if the class responds to ar, kr or ir classmethods.
|
||
|
|
|
||
|
|
section:: Parser node tree output
|
||
|
|
The SCDoc parser outputs a tree of link::Classes/SCDocNode::s
|
||
|
|
|
||
|
|
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
|
||
|
|
tree::
|
||
|
|
## HEADER
|
||
|
|
tree::
|
||
|
|
## TITLE teletype::"SinOsc"::
|
||
|
|
## SUMMARY teletype::"Interpolating sine wavetable oscillator"::
|
||
|
|
## RELATED
|
||
|
|
tree::
|
||
|
|
## STRING teletype::"Classes/FSinOsc"::
|
||
|
|
## STRING teletype::"Classes/SinOscFB"::
|
||
|
|
::
|
||
|
|
## CATEGORIES
|
||
|
|
tree::
|
||
|
|
## STRING teletype::"UGens>Generators>Deterministic"::
|
||
|
|
## STRING teletype::"UGens>Oscillators"::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
## BODY
|
||
|
|
tree::
|
||
|
|
## DESCRIPTION
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"A paragraph with "::
|
||
|
|
## LINK teletype::"Classes/Osc##a link"::
|
||
|
|
## TEXT teletype::" to another document."::
|
||
|
|
::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Another paragraph with "::
|
||
|
|
## STRONG teletype::"strong words"::
|
||
|
|
## TEXT teletype::" in it."::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
## CLASSMETHODS
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Some text..."::
|
||
|
|
::
|
||
|
|
## CMETHOD
|
||
|
|
tree::
|
||
|
|
## METHODNAMES
|
||
|
|
tree::
|
||
|
|
## STRING teletype::"ar"::
|
||
|
|
## STRING teletype::"kr"::
|
||
|
|
::
|
||
|
|
## METHODBODY
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Some text..."::
|
||
|
|
::
|
||
|
|
## ARGUMENTS
|
||
|
|
tree::
|
||
|
|
## ARGUMENT teletype::"freq"::
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Frequency in hertz"::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
## ARGUMENT teletype::"phase"::
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Phase modulation"::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
## EXAMPLES
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Here are some examples:"::
|
||
|
|
::
|
||
|
|
## CODEBLOCK
|
||
|
|
teletype::
|
||
|
|
"{ 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;"
|
||
|
|
::
|
||
|
|
::
|
||
|
|
## SECTION teletype::"Another section"::
|
||
|
|
tree::
|
||
|
|
## PROSE
|
||
|
|
tree::
|
||
|
|
## TEXT teletype::"Some text..."::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
::
|
||
|
|
|