SCDoc manages the SuperCollider documentation system.
It uses SCDocParser for parsing and SCDocRenderer for rendering.
The syntax reference for the documentation markup language can be found here: SCDocSyntax.
A guide to writing help can be found here: Writing Help.
Get help URL for a specific string:
url = SCDoc.prepareHelpForURL(SCDoc.findHelpFile("SinOsc"));
The default SCDocParser object, created automatically.
The default SCDocRenderer object, created automatically. Defaults to an instance of SCDocHTMLRenderer
get/set the system-wide directory of help sourcefiles. Defaults to thisProcess.platform.classLibraryDir.dirname +/+ "HelpSource"
get the list of HelpSource folders, including extensions and quarks.
This searches recursively for all folders named "HelpSource" under thisProcess.platform.userExtensionDir and thisProcess.platform.systemExtensionDir as well as including the system-wide helpSourceDir
get/set the user help target directory. Defaults to thisProcess.platform.userAppSupportDir +/+ "Help"
A set of all undocumented classes.
If true, print progress status messages to post window.
Prepare help for the given URL by checking if the file needs rendering from schelp source, or some other action needs to be done.
Use this as a wrapper to get on-the-fly rendering and processing of help files.
If called from a routine, do some 0.wait while running to give the GUI a chance to respond.
| url |
The url to prepare. If this is not a local file inside *helpTargetDir then it will just pass through the url directly. |
the URL or nil if file not found.
Find help for a given string. This method redirects to the instance method findHelpFile on the current renderer object.
the URL for help on given string
Render all help-files that need updating and generate overviews and cached metadata index. This can take several minutes. Useful mainly if you want to render all help to put online or similar.
| force |
Force updating of all files. |
| threaded |
When true, runs the process in a Routine on AppClock. This is needed to get progress feedback when running inside a frontend like the SuperCollider app on OSX. If running with the sclang terminal client, this can be set to false for better performance. |
| findExtensions |
If false, don't search for extensions (useful when building base help) |
| doneFunc |
Function to evaluate when done. |
It traverses the directory tree recursively starting at helpSourceDir, parsing and rendering all *.schelp files and copying all other files. The output goes to an equal directory layout in helpTargetDir.
Parse and render a specific file.
| src |
The .schelp source document file, must be full path. |
| dest |
The destination target file ( .html if current renderer is SCDocHTMLRenderer ), must be full path. |
| kind |
The document "kind", like Classes, Reference, Overviews, Guides. Should be the same as the parent folder name of both |
SCDoc keeps a dictionary where each document is represented by an Event with the keys path, title, categories, summary, installed.
SCDoc also writes the document map in JSON format to helpTargetDir/docmap.js.
Returns the internal dictionary of documents.
An internal Dictionary, it will be empty if there was no docmap cache file.
If the document map cache was not already read from file, it's first read from file if existent.
The returned Dictionary is indexed by the documents path relative helpSourceDir, and without file suffix. Like Classes/SCDoc.
This dictionary is cached in helpTargetDir/scdoc_cache.
Creates a dictionary of all categories, with a list of documents for each category.
A Dictionary of all documents grouped by category.
The keys are category symbols, and each value is a List of Events representing each document.
Reset the state so that next time *prepareHelpForURL is called, SCDoc will collect any newly added HelpSource files and undocumented classes.
| noCache |
If true, don't read doc map cache from file and discard any old rendered files. This makes sure that every file is re-rendered, even if there was already a rendered help file. This is similar to starting with an empty Help folder. |
Create a schelp template for specified class.
| name |
String or Symbol. The name of the class. |
| path |
File to render the help stub and template to, used internally by SCDoc. Just pass nil (default) to return the template string. |
If path was given, true or false. If not given, returns the template string.
Split a comma-separated string into an array of whitespace-stripped strings, useful to parse the contents of tags like categories:: and related::.
| txt |
The string to split. |
An Array of whitespace-stripped strings.
Find the helpsource for a help path, if existent.
| subtarget |
The sub-path for a help file, like "Guides/WritingHelp" or "Classes/SinOsc". |
The path to the .schelp file, or nil if no file found.
Example:
SCDoc.findHelpSource("Classes/SCDoc"); // a path SCDoc.findHelpSource("NoSuch/File"); // nil