HelpSource/Classes/SCDoc.schelp

   1 class:: SCDoc
   2 summary:: Help system main class
   3 categories:: HelpSystem
   4 related:: Reference/SCDocSyntax, Guides/WritingHelp, Classes/SCDocHTMLRenderer, Classes/SCDocNode, Classes/SCDocEntry
   5
   6 DESCRIPTION::
   7 SCDoc manages the SuperCollider documentation system.
   8
   9 It uses parses help files written in link::Reference/SCDocSyntax##SCDoc markup language:: and renders them as human-readable documents.
  10
  11 A guide to writing help can be found here: link::Guides/WritingHelp::.
  12
  13 CLASSMETHODS::
  14
  15 subsection:: Document index
  16
  17 method:: indexAllDocuments
  18 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.
  19
  20 Run this method if you added a new document and want to see the changes without restarting SuperCollider.
  21
  22 argument:: clearCache
  23 If true, force re-render of files even if the schelp source file is not newer than the destination.
  24
  25 discussion::
  26 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.
  27
  28 method:: documents
  29 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::
  30
  31 method:: didIndexDocuments
  32 A Boolean indicating if code::SCDoc.indexAllDocuments:: was called in this session yet.
  33
  34 method:: helpSourceDir
  35 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.
  36
  37 method:: helpSourceDirs
  38 get the list of HelpSource folders, including extensions and quarks.
  39 discussion::
  40 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::
  41
  42 method:: findHelpFile
  43 Find help for a given string. Tries to be smart.
  44 returns:: the URL for help on given string
  45
  46 method:: verbosity
  47 Verbosity level. 0 is silent.
  48
  49 subsection:: Parsing and Rendering
  50
  51 private:: checkVersion, exportDocMapJS, handleCopyMethods, postMsg, prParseFile, renderUndocClass
  52
  53 method:: renderer
  54 The default renderer, defaults to link::Classes/SCDocHTMLRenderer::
  55
  56 method:: helpTargetDir
  57 get/set the user help target directory. Defaults to code::Platform.userAppSupportDir +/+ "Help":: and should typically not be changed by the user.
  58
  59 method:: parseFileFull
  60 Parse file.
  61 argument::
  62 Full path to .schelp file
  63 returns::
  64 An link::Classes/SCDocNode:: tree
  65
  66 method:: parseFileMetaData
  67 Parse only the stuff needed for metadata.
  68 argument::
  69 Base HelpSource directory.
  70 argument::
  71 Path relative above dir.
  72 returns::
  73 An link::Classes/SCDocNode:: tree
  74
  75 method:: parseFilePartial
  76 Parse a file without header, for merging of document additions
  77 argument::
  78 Full path to .ext.schelp file
  79 returns::
  80 An link::Classes/SCDocNode:: tree
  81
  82 method:: parseDoc
  83 Parse the files associated with an link::Classes/SCDocEntry::, including any document additions (teletype::*.ext.schelp::)
  84 argument:: doc
  85 The link::Classes/SCDocEntry:: to parse.
  86 returns::
  87 An link::Classes/SCDocNode:: tree
  88
  89 method:: parseAndRender
  90 Parse and render a specific document.
  91 argument:: doc
  92 The link::Classes/SCDocEntry:: to parse and render.
  93
  94 method:: renderAll
  95 Render all help-files. Useful mainly if you want to render all help to put online or similar.
  96 argument:: includeExtensions
  97 If false, skip quarks, plugins and other extensions.
  98
  99 method:: prepareHelpForURL
 100 Prepare help for the given URL by checking if the file needs rendering from schelp source, or some other action needs to be done.
 101 Used as a wrapper to get on-the-fly rendering and processing of help files.
 102 argument:: url
 103 The url to prepare. If this is not a local file inside link::#*helpTargetDir:: then it will just pass through the url directly.
 104 returns:: the URL or nil if file not found.
 105
 106 subsection:: Utilities
 107
 108 method:: getMethodDoc
 109 Extract the link::Classes/SCDocNode:: tree for the specified method documentation.
 110 argument::
 111 Name of class
 112 argument::
 113 Name of method, prefixed with teletype::*:: for classmethods and teletype::-:: for instancemethods.
 114 returns::
 115 An link::Classes/SCDocNode:: tree
 116
 117 method:: makeClassTemplate
 118 Create a schelp template for specified class.
 119 argument:: doc
 120 The link::Classes/SCDocEntry:: for the undocumented class.
 121 returns::
 122 Returns the template string.
 123
 124 method:: classHasArKrIr
 125 argument:: c
 126 The link::Classes/Class:: to check.
 127 Returns:: code::true:: if the class responds to ar, kr or ir classmethods.
 128
 129 section:: Parser node tree output
 130 The SCDoc parser outputs a tree of link::Classes/SCDocNode::s
 131
 132 The nodes reflects the tags in the input, but it's not a one-to-one correspondation.
 133 A more detailed structure is added in the node tree, for easier rendering.
 134
 135 Example:
 136
 137 DOCUMENT
 138 tree::
 139     ## HEADER
 140     tree::
 141         ## TITLE teletype::"SinOsc"::
 142         ## SUMMARY teletype::"Interpolating sine wavetable oscillator"::
 143         ## RELATED
 144         tree::
 145             ## STRING teletype::"Classes/FSinOsc"::
 146             ## STRING teletype::"Classes/SinOscFB"::
 147         ::
 148         ## CATEGORIES
 149         tree::
 150             ## STRING teletype::"UGens>Generators>Deterministic"::
 151             ## STRING teletype::"UGens>Oscillators"::
 152         ::
 153     ::
 154     ## BODY
 155     tree::
 156         ## DESCRIPTION
 157         tree::
 158             ## PROSE
 159             tree::
 160                 ## TEXT teletype::"A paragraph with "::
 161                 ## LINK teletype::"Classes/Osc##a link"::
 162                 ## TEXT teletype::" to another document."::
 163             ::
 164             ## PROSE
 165             tree::
 166                 ## TEXT teletype::"Another paragraph with "::
 167                 ## STRONG teletype::"strong words"::
 168                 ## TEXT teletype::" in it."::
 169             ::
 170         ::
 171         ## CLASSMETHODS
 172         tree::
 173             ## PROSE
 174             tree::
 175                 ## TEXT teletype::"Some text..."::
 176             ::
 177             ## CMETHOD
 178             tree::
 179                 ## METHODNAMES
 180                 tree::
 181                     ## STRING teletype::"ar"::
 182                     ## STRING teletype::"kr"::
 183                 ::
 184                 ## METHODBODY
 185                 tree::
 186                     ## PROSE
 187                     tree::
 188                         ## TEXT teletype::"Some text..."::
 189                     ::
 190                     ## ARGUMENTS
 191                     tree::
 192                         ## ARGUMENT teletype::"freq"::
 193                         tree::
 194                             ## PROSE
 195                             tree::
 196                                 ## TEXT teletype::"Frequency in hertz"::
 197                             ::
 198                         ::
 199                         ## ARGUMENT teletype::"phase"::
 200                         tree::
 201                             ## PROSE
 202                             tree::
 203                                 ## TEXT teletype::"Phase modulation"::
 204                             ::
 205                         ::
 206                     ::
 207                 ::
 208             ::
 209         ::
 210         ## EXAMPLES
 211         tree::
 212             ## PROSE
 213             tree::
 214                 ## TEXT teletype::"Here are some examples:"::
 215             ::
 216             ## CODEBLOCK
 217             teletype::
 218 "{ SinOsc.ar(200, 0, 0.5) }.play;
 219 // modulate freq
 220 { SinOsc.ar(XLine.kr(2000, 200), 0, 0.5) }.play;
 221 // modulate freq
 222 { SinOsc.ar(SinOsc.ar(XLine.kr(1, 1000, 9), 0, 200, 800), 0, 0.25) }.play;
 223 // modulate phase
 224 { SinOsc.ar(800, SinOsc.ar(XLine.kr(1, 1000, 9), 0, 2pi), 0.25) }.play;"
 225 ::
 226         ::
 227         ## SECTION teletype::"Another section"::
 228         tree::
 229             ## PROSE
 230             tree::
 231                 ## TEXT teletype::"Some text..."::
 232             ::
 233         ::
 234     ::
 235 ::
 236