HelpSource/Classes/SCDoc.schelp

   1 class:: SCDoc
   2 summary:: Help system main class
   3 categories:: HelpSystem
   4 related:: Classes/SCDocParser, Classes/SCDocRenderer, Guides/WritingHelp, Reference/SCDocSyntax
   5
   6 DESCRIPTION::
   7 SCDoc manages the SuperCollider documentation system.
   8
   9 It uses link::Classes/SCDocParser:: for parsing and link::Classes/SCDocRenderer:: for rendering.
  10
  11 The syntax reference for the documentation markup language can be found here: link::Reference/SCDocSyntax::.
  12
  13 A guide to writing help can be found here: link::Guides/WritingHelp::.
  14
  15 SUBSECTION:: Basic usage
  16 Get help URL for a specific string:
  17 code::
  18 url = SCDoc.prepareHelpForURL(SCDoc.findHelpFile("SinOsc"));
  19 ::
  20
  21 CLASSMETHODS::
  22 private:: initClass, addToDocMap, makeMethodList, postProgress, docMapToJSON, handleUndocumentedClasses, writeDocMap, collectAllMethods, tickProgress, readDocMap, addMethodList, findHelpSourceDirs, getAllMetaData, syncNonHelpFiles, maybeWait, checkVersion
  23
  24 method:: p
  25 The default link::Classes/SCDocParser:: object, created automatically.
  26 method:: r
  27 The default link::Classes/SCDocRenderer:: object, created automatically. Defaults to an instance of link::Classes/SCDocHTMLRenderer::
  28
  29 method:: helpSourceDir
  30 get/set the system-wide directory of help sourcefiles. Defaults to code::thisProcess.platform.classLibraryDir.dirname +/+ "HelpSource"::
  31
  32 method:: helpSourceDirs
  33 get the list of HelpSource folders, including extensions and quarks.
  34 discussion::
  35 This searches recursively for all folders named "HelpSource" under code::thisProcess.platform.userExtensionDir:: and code::thisProcess.platform.systemExtensionDir:: as well as including the system-wide code::helpSourceDir::
  36
  37 method:: helpTargetDir
  38 get/set the user help target directory. Defaults to code::thisProcess.platform.userAppSupportDir +/+ "Help"::
  39
  40 method:: undocumentedClasses
  41 A set of all undocumented classes.
  42
  43 method:: verbose
  44 If code::true::, print progress status messages to post window.
  45
  46 subsection:: Main interface
  47
  48 method:: prepareHelpForURL
  49 Prepare help for the given URL by checking if the file needs rendering from schelp source, or some other action needs to be done.
  50 Use this as a wrapper to get on-the-fly rendering and processing of help files.
  51 If called from a routine, do some code::0.wait:: while running to give the GUI a chance to respond.
  52 argument:: url
  53 The url to prepare. If this is not a local file inside link::#*helpTargetDir:: then it will just pass through the url directly.
  54 returns:: the URL or nil if file not found.
  55
  56 method:: findHelpFile
  57 Find help for a given string. This method redirects to the instance method code::findHelpFile:: on the current renderer object.
  58 returns:: the URL for help on given string
  59
  60 subsection:: Render all or specific files
  61
  62 method:: renderAll
  63 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.
  64 argument:: force
  65 Force updating of all files.
  66 argument:: threaded
  67 When true, runs the process in a link::Classes/Routine:: on link::Classes/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.
  68 argument:: findExtensions
  69 If false, don't search for extensions (useful when building base help)
  70 argument:: doneFunc
  71 Function to evaluate when done.
  72 discussion::
  73 It traverses the directory tree recursively starting at code::helpSourceDir::, parsing and rendering all *.schelp files and copying all other files. The output goes to an equal directory layout in code::helpTargetDir::.
  74
  75 method:: parseAndRender
  76 Parse and render a specific file.
  77 argument:: src
  78 The .schelp source document file, must be full path.
  79 argument:: dest
  80 The destination target file ( .html if current renderer is link::Classes/SCDocHTMLRenderer:: ), must be full path.
  81 argument:: kind
  82 The document "kind", like Classes, Reference, Overviews, Guides. Should be the same as the parent folder name of both code::src:: and code::dest::
  83
  84 subsection:: Cached map of documents
  85 SCDoc keeps a dictionary where each document is represented by an link::Classes/Event:: with the keys code::path, title, categories, summary, installed::.
  86
  87 SCDoc also writes the document map in JSON format to code::helpTargetDir/docmap.js::.
  88
  89 method:: docMap
  90 Returns the internal dictionary of documents.
  91 returns:: An internal link::Classes/Dictionary::, it will be empty if there was no docmap cache file.
  92 discussion::
  93 If the document map cache was not already read from file, it's first read from file if existent.
  94 The returned Dictionary is indexed by the documents path relative helpSourceDir, and without file suffix. Like code::Classes/SCDoc::.
  95
  96 This dictionary is cached in code::helpTargetDir/scdoc_cache::.
  97
  98 method:: makeCategoryMap
  99 Creates a dictionary of all categories, with a list of documents for each category.
 100 returns:: A link::Classes/Dictionary:: of all documents grouped by category.
 101 discussion:: The keys are category symbols, and each value is a link::Classes/List:: of Events representing each document.
 102
 103 method:: cleanState
 104 Reset the state so that next time link::#*prepareHelpForURL:: is called, SCDoc will collect any newly added HelpSource files and undocumented classes.
 105 argument:: noCache
 106 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.
 107
 108 subsection:: Utilities
 109
 110 method:: makeClassTemplate
 111 Create a schelp template for specified class.
 112 argument:: name
 113 String or Symbol. The name of the class.
 114 argument:: path
 115 File to render the help stub and template to, used internally by SCDoc. Just pass nil (default) to return the template string.
 116 returns::
 117 If path was given, true or false. If not given, returns the template string.
 118
 119 method:: splitList
 120 Split a comma-separated string into an array of whitespace-stripped strings, useful to parse the contents of tags like code::categories\:::: and code::related\::::.
 121 argument:: txt
 122 The string to split.
 123 returns:: An link::Classes/Array:: of whitespace-stripped strings.
 124
 125 method:: classHasArKrIr
 126 argument:: c
 127 The link::Classes/Class:: to check.
 128 Returns:: code::true:: if the class responds to ar, kr or ir classmethods.
 129
 130 method:: findHelpSource
 131 Find the helpsource for a help path, if existent.
 132 argument:: subtarget
 133 The sub-path for a help file, like "Guides/WritingHelp" or "Classes/SinOsc".
 134 returns:: The path to the .schelp file, or nil if no file found.
 135 discussion::
 136 Example:
 137 code::
 138 SCDoc.findHelpSource("Classes/SCDoc"); // a path
 139 SCDoc.findHelpSource("NoSuch/File"); // nil
 140 ::