SCDoc:
Filter:
Classes | HelpSystem

SCDoc : Object

Help system main class
Source: SCDoc.sc

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

SCDoc.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.

SCDoc.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

SCDoc.didIndexDocuments

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

SCDoc.helpSourceDir

SCDoc.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.

SCDoc.helpSourceDirs

get the list of HelpSource folders, including extensions and quarks (unless they are excluded from library compilation, e.g. by LanguageConfig: *excludeDefaultPaths)

Discussion:

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.

SCDoc.findHelpFile(str)

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

Returns:

the URL for help on given string

SCDoc.verbosity

SCDoc.verbosity = value

Verbosity level. 0 is silent.

Parsing and Rendering

SCDoc.renderer

SCDoc.renderer = value

The default renderer, defaults to SCDocHTMLRenderer

SCDoc.helpTargetDir

SCDoc.helpTargetDir = path

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

SCDoc.parseFileFull(path)

Parse file.

Arguments:

path

Full path to .schelp file

Returns:

An SCDocNode tree

SCDoc.parseFileMetaData(dir, path)

Parse only the stuff needed for metadata.

Arguments:

dir

Base HelpSource directory.

path

Path relative above dir.

Returns:

An SCDocNode tree

SCDoc.parseFilePartial(path)

Parse a file without header, for merging of document additions

Arguments:

path

Full path to .ext.schelp file

Returns:

An SCDocNode tree

SCDoc.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

SCDoc.parseAndRender(doc)

Parse and render a specific document.

Arguments:

doc

The SCDocEntry to parse and render.

SCDoc.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.

SCDoc.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

SCDoc.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

SCDoc.makeClassTemplate(doc)

Create a schelp template for specified class.

Arguments:

doc

The SCDocEntry for the undocumented class.

Returns:

Returns the template string.

SCDoc.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

SCDoc.getOldWrapUrl(url)

SCDoc.helpTargetUrl

SCDoc.indexOldHelp

SCDoc.prRescanHelpSourceDirs

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