The simplest way is to look at an existing help file or class document, and read this document and SCDoc Syntax
All tags that are used for document metadata should be entered at the top of the document source file, before any section or other text. See SCDoc Syntax: Header tags
In the header, you must specify the title, summary and categories parts of the header.
Example header:
title:: My help file summary:: A short single-line summary of what this is categories:: Language>Conditionals, SomeOtherCategory related:: Reference/FooBar
Use regular text in sections and subsections, and possible other tags for lists, tables, trees, images, links, etc.. See SCDoc Syntax for tag reference.
section:: Introduction This is a nice document... blah blah blah.. subsection:: Details Some details..
When you navigate to an undocumented class, it will contain an schelp template that can be filled in and saved to HelpSource/Classes/ClassName.schelp.
A list of all undocumented classes can be seen here: Browse: Undocumented classes (auto-generated).
The help system uses different folders under HelpSource depending on document kind:
All .schelp files will be parsed and rendered to an equal directory layout in the help target directory. Any other files, like images or ready-made HTML files, will just be copied.
Class reference has some special tags and a more strict structure. Normal text should be written inside the special top-level sections DESCRIPTION, CLASSMETHODS, INSTANCEMETHODS and EXAMPLES.
Named subsections can be used under each of the above mentioned top-level sections.
Also named sections can be used, but they will be put after all above top-level sections.
Methods are documented like this:
method:: name(s)argument:: name1argument:: name2returns::discussion::After the method description comes the arguments, written with argument:: name where name is optional, and will be auto-filled in if not given. If given, it must match the real argument name of the method. After each argument line comes the description of that argument.
There is an optional returns:: tag that could be used to describe the methods return value.
If a longer discussion is needed, use the discussion:: tag. This is a good place to insert example code, etc.
Setters are handled automagically, when documenting a setter/getter, use only the getter name (no underscore) and describe both setter and getter as a single property, example:
method:: helpSourceDir set or get the help source directory
Methods get an anchor name automatically, prefixed with * for class methods and - for instance methods. For example, to link to the foo class method, use link::#*foo::.
The method:: tag can be used also in normal documents, and should then have argumentnames. This can be useful for documenting common interfaces outside of a specific class document, for example plot. Anchors for these methods get prefixed with a dot (.) instead of * or -.
When multiple methods have the same signature (like ar and kr in ugens), they should all be listed in one single method tag.
SCDoc generates docs for all undocumented methods. To ignore private methods, add them to a private:: tag, which works just like the method tag but without a section body.
Extensions can add methods to existing class docs, see the Extensions section below.
You can use copymethod:: ClassName, methodName to copy the documentation of a method from another helpfile to this one.
methodName must be prefixed with * (asterix) for class methods and - (dash) for instance methods.
Some classes uses the *doesNotUnderstand trick to redirect to another implementing class. To document such classes, you need to add this tag in the header:
redirect:: implClass
Where implClass is the name of the class variable holding the implementing class.
An example of documentation for LFPulse UGen, saved to HelpSource/Classes/LFPulse.schelp
TITLE:: LFPulse
summary:: pulse oscillator
categories:: UGens>Generators>Deterministic, UGens>Oscillators
related:: Classes/LFSaw
DESCRIPTION::
A non-band-limited pulse oscillator. Outputs a high value of one and a low value of zero.
CLASSMETHODS::
private:: categories
METHOD:: ar, kr
argument::freq
frequency in Hertz
argument::iphase
initial phase offset in cycles ( 0..1 )
argument::width
pulse width duty cycle from zero to one.
returns::
An UGen.
EXAMPLES::
a plot:
code:: { LFPulse.ar(Line.kr(100, 800, 0.1)) }.plot(0.1); ::
50 Hz wave:
code:: { LFPulse.ar(50) * 0.1 }.play; ::Try to find good categories for the doc you are writing/converting. If a suitable category already exists, you should use that. See the Document Browser (auto-generated) for existing categories.
For UGens, you should use the existing categories like UGens>Filter>Nonlinear. View the current categories like this:
Documents can exist in multiple categories, and also have hierarchical categories, like Sequencing>Patterns.
To link another document, use link::Path/To/Document:: where the path is relative to SCDoc: *helpTargetDir and the document filename is with no extension. Example:
Also take a look at link::Classes/SinOsc:: and link::Reference/Literals::
To link to a specific class method, append #*methodName or to an instance method, append #-methodName:
Also take a look at the play method of link::Classes/Function#-play::
This will render as Function: -play
For generic methods documented outside of instancemethods or classmethods (like the generic play document), use a dot (.) as prefix instead of * or -.
The special Methods overview is dynamic and allows a specific method to be shown by appending #name where name is the name of the method:
For all implementations of play, see link::Overviews/Methods#play::
The Search page can match on document title/filename, summary, non-private methods, and categories. If you mention something that should match in search but is not one of the above, you can explicitly add it with the keyword tag:
keyword:: someKeyWords
Each extension should have their own HelpSource folder with files that should be included in the help system.
Example file layout:
If you want to set a main help file for the quark, set \schelp in the Quark directory file to the path for the help file relative to HelpSource and without the .schelp extension. Example: \schelp: "Guides/MyGuide"
An extension that adds methods to existing classes should document these in Classes/TheClass.ext.schelp, only including the relevant bits (no title, summary, categories, etc..)
Example: Classes/String.ext.schelp
INSTANCEMETHODS:: subsection:: Extensions by SCDoc method:: stripWhiteSpace strips whitespace at the beginning and end of the string returns:: the stripped string
The contents are inserted into the right spot (section, subsection, etc). It works for all kind of sections, for example one can add a subsection to DESCRIPTION:: with additional information, or add another top-level section, etc.
URL's are automagically converted to links.
The link:: tag is used for cross-reference between docs. It uses a simple namespace, example:
Anchors can be inserted manually with anchor::name:: and referenced like this:
or to jump to an anchor in this document:
All sections get anchor names automagically.
All methods get anchor names prefixed with * for class methods and - for instance methods.
One can change the rendered text of the link by using another # character:
A link to specific methods:
Renders as: SinOsc: *ar and Function: -play
The Methods overview is dynamic and allows a specific method to be shown, by using the methodname as anchor, for example to get a list of all classes implementing play :
Renders as: All classes implementing play can be seen here.
The Browse page is also dynamic, and can take a category tree as anchor name:
Renders as: For more filters, see Browse: UGens>Filters
The easiest way to contribute to the documentation is:
1. Fork the SuperCollider repository https://github.com/supercollider/supercollider
2. Clone your repository
3. Create a branch for doc updates
4. Do your update, commit your changes and push to github
5. Submit your pull request through github, from your branch doc_updates to SuperCollider develop
Here is some information for working with documentation that is written in legacy format or syntax.
SCDoc was rewritten and the parser implemented in C++ for speed and stability in 3.5.2. The syntax got more strict, and the parser now throws errors or warnings if there are faults in the documentation.
Some important changes to keep in mind:
link::#Language-side news:: renders: Language-side newsSCDoc.indexAllDocuments if you add a new document or other file and want to see the change reflected in the help. If you just changed a document and want to see the changes, just press Reload in the browser and SCDoc will detect and re-index automatically.CLASS:: tag is deprecated, just use TITLE:: instead also for class reference docs.ARGUMENT:: tag is now optional. If not given, SCDoc will auto-fill the real argument name.There is no automated process for this, but for most help files it's really simple to do it manually:
SCDoc.indexAllDocuments (link to method documentation: SCDoc: *indexAllDocuments) to make SCDoc detect the new file and add it to the document index.
If the file already existed and you want to see the changes, just press Reload in the help browser and SCDoc will re-render it.