SuperCollider CLASSES

SCDoc

Help system main class
Inherits from: Object

Description

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.

Class Methods

Document index

*indexAllDocuments (clearCache: false)

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.

Arguments:

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.

*documents

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

*didIndexDocuments

A Boolean indicating if SCDoc.indexAllDocuments was called in this session yet.

*helpSourceDir

*helpSourceDir = path

get/set the system-wide directory of help sourcefiles. Defaults to Platform.classLibraryDir.dirname +/+ "HelpSource" and should typically not be changed by the user.

*helpSourceDirs

get the list of HelpSource folders, including extensions and quarks.

Discussion:

This searches recursively for all folders named "HelpSource" under Platform.userExtensionDir and Platform.systemExtensionDir as well as including the system-wide helpSourceDir

*findHelpFile (str)

Find help for a given string. Tries to be smart.

Returns:

the URL for help on given string

*verbosity

*verbosity = value

Verbosity level. 0 is silent.

Parsing and Rendering

*renderer

*renderer = value

The default renderer, defaults to SCDocHTMLRenderer

*helpTargetDir

*helpTargetDir = path

get/set the user help target directory. Defaults to Platform.userAppSupportDir +/+ "Help" and should typically not be changed by the user.

*parseFileFull (path)

Parse file.

Arguments:

path

Full path to .schelp file

Returns:

An SCDocNode tree

*parseFileMetaData (dir, path)

Parse only the stuff needed for metadata.

Arguments:

dir

Base HelpSource directory.

path

Path relative above dir.

Returns:

An SCDocNode tree

*parseFilePartial (path)

Parse a file without header, for merging of document additions

Arguments:

path

Full path to .ext.schelp file

Returns:

An SCDocNode tree

*parseDoc (doc)

Parse the files associated with an SCDocEntry, including any document additions (*.ext.schelp)

Arguments:

doc

The SCDocEntry to parse.

Returns:

An SCDocNode tree

*parseAndRender (doc)

Parse and render a specific document.

Arguments:

doc

The SCDocEntry to parse and render.

*renderAll (includeExtensions: true)

Render all help-files. Useful mainly if you want to render all help to put online or similar.

Arguments:

includeExtensions

If false, skip quarks, plugins and other extensions.

*prepareHelpForURL (url)

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.

Arguments:

url

The url to prepare. If this is not a local file inside *helpTargetDir then it will just pass through the url directly.

Returns:

the URL or nil if file not found.

Utilities

*getMethodDoc (classname, methodname)

Extract the SCDocNode tree for the specified method documentation.

Arguments:

classname

Name of class

methodname

Name of method, prefixed with * for classmethods and - for instancemethods.

Returns:

An SCDocNode tree

*makeClassTemplate (doc)

Create a schelp template for specified class.

Arguments:

doc

The SCDocEntry for the undocumented class.

Returns:

Returns the template string.

*classHasArKrIr (c)

Arguments:

c

The Class to check.

Returns:

true if the class responds to ar, kr or ir classmethods.

Inherited class methods

Undocumented class methods

*getOldWrapUrl (url)

*helpTargetUrl

*indexOldHelp

Instance Methods

Inherited instance methods

Parser node tree output

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