/usr/share/SuperCollider/HelpSource/Classes/SCDoc.schelp

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..."::
            ::
        ::
    ::
::
supercollider-common 1:3.8.0~repack-2 / usr / share / SuperCollider / HelpSource / Classes / SCDoc.schelp
