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...":: :: :: :: ::