HelpSource/Guides/WritingHelp.schelp

   1 title:: Writing Help
   2 summary:: Get started with writing help
   3 categories:: HelpSystem
   4 related:: Reference/SCDocSyntax, Classes/SCDoc
   5
   6 section:: Writing new help
   7 The simplest way is to look at an existing help file or class document, and read this document and link::Reference/SCDocSyntax::
   8
   9 note:: The help files should use UTF-8 encoding! ::
  10
  11 subsection:: Documenting new classes
  12 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.
  13
  14 section:: Converting old helpfiles
  15
  16 Currently there is no automated process for this, but for most help files it's really simple to do it manually:
  17
  18 numberedlist::
  19 ## open the old helpfile in your web browser
  20 ## copy the text and insert it in a new textfile: FileName.schelp
  21 ## add the appropriate tags, like title, sections, etc.. (see below)
  22 ## save the file to the right subdirectory under HelpSource, depending on the document kind (see link::#directory_layout:: below)
  23 ## strong:: check that it rendered OK ::.
  24 You can run code::SCDoc.cleanState:: (link to method documentation: link::Classes/SCDoc#*cleanState::) to make SCDoc detect the new file and add it to the doc map next time you open a file in the link::Classes/HelpBrowser::. If the file already existed and you want to see the changes, just navigate to it again and SCDoc will re-render it.
  25 ::
  26
  27 A list of all undocumented classes can be seen here: link::Browse#Undocumented classes#Undocumented classes:: (auto-generated).
  28
  29 section:: Directory layout
  30 The help system uses different folders under HelpSource depending on document kind:
  31 definitionlist::
  32 ## HelpSource ||
  33 definitionlist::
  34 ## Classes || class reference, file must be named as the class.
  35 ## Reference || other reference documentation.
  36 ## Tutorials || yes, tutorials.
  37 ## Guides || guides that explain stuff but without beeing a real tutorial.
  38 ## Overviews || overviews of other documents, these are mostly auto-generated.
  39 ## Other || stuff that don't fit in any other directory.
  40 ::
  41 ::
  42
  43 note:: It's important that the document is put in the right folder. For Classes, it's a must! ::
  44
  45 All .schelp files will be parsed and rendered to an equal directory layout in the help target directory. Any other files will just be copied.
  46
  47 section:: Metadata
  48
  49 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. These include:
  50 code::
  51 title:: or class::
  52 summary::
  53 related::
  54 categories::
  55 ::
  56
  57 You should always specify title/class, summary and categories.
  58
  59 section:: Normal documents
  60 Normal documents use code::title:: for the document title.
  61
  62 Example header:
  63 code::
  64 title:: My help file
  65 summary:: A short single-line summary of what this is
  66 categories:: Language>Conditionals, AndSoOn
  67 related:: Reference/FooBar
  68 ::
  69
  70 Then use normal text in sections and subsections, and possible other tags for lists, tables, trees, images, links, etc.. See link::Reference/SCDocSyntax:: for tag reference.
  71
  72 code::
  73 section:: Introduction
  74 this is a nice document...
  75 blah blah blah..
  76
  77 subsection:: Details
  78 some details..
  79 ::
  80
  81 section:: Class reference
  82 Class reference has some special tags and a more strict structure. Instead of title tag we use class tag, and normal text should be written inside the special top-level sections code::description::, code::classmethods::, code::instancemethods:: and code::examples::.
  83
  84 Named subsections can be used under each of the above mentioned top-level sections.
  85
  86 Also named sections can be used, but they will be put after all above top-level sections.
  87
  88 subsection:: Methods and arguments
  89 Methods are documented with the tags:
  90 tree::
  91 ## code::method\:::: name(s)
  92     tree::
  93     ## short description of method
  94     ## code::argument\:::: name
  95     tree::
  96         ## description of argument
  97         ::
  98     ## code::argument\:::: name
  99     tree::
 100         ## description of argument
 101         ::
 102     ## code::returns\::::
 103     tree::
 104         ## description of return value
 105         ::
 106     ## code::discussion\::::
 107     tree::
 108         ## optional discussion and example code
 109         ::
 110     ::
 111 ::
 112
 113 note:: Don't list arguments in the method tag, only the method names ::
 114
 115 Setters are handled automagically, when documenting a setter/getter, use only the getter name (no underscore) and describe both setter and getter, example:
 116 code::
 117 method:: helpSourceDir
 118 set or get the help source directory
 119 ::
 120
 121 The code::method\:::: tag can be used also in normal documents, and should then have argumentnames. This can be useful for documenting common methods outside of a specific class document, for example link::Reference/plot::.
 122 Anchors for these methods get prefixed with a dot (.) instead of * or -.
 123
 124 SCDoc generates docs for all undocumented methods. To ignore private methods, add them to a code::private\:::: tag right after code::classmethods\:::: or code::instancemethods\::::
 125
 126 Extensions can add methods to existing class docs, see the link::#extensions:: section below.
 127
 128 subsection:: Redirect classes
 129 Some classes uses the code::*doesNotUnderstand:: trick to redirect to another implementing class. To document such classes, you need to add this tag in the header:
 130 code::
 131 redirect:: implClass
 132 ::
 133 Where code::implClass:: is the class variable name holding the implementing class.
 134
 135 subsection:: Example
 136
 137 code::
 138 CLASS:: MyClass
 139 summary:: a nice class to do that and this
 140 categories:: Collections>SuperCollections, OtherCategories, AndSoOn
 141 related:: Classes/AnotherClass, Reference/MyClassCommandReference
 142
 143 DESCRIPTION::
 144 Here goes a long description of what the class does and why, etc..
 145
 146 CLASSMETHODS::
 147 private:: myPrivateClassMethod
 148
 149 method:: foo
 150 here goes a description of the class method foo
 151 argument:: x
 152 here goes a description of argument x of method foo
 153 argument:: y
 154 here goes a description of argument y of method foo
 155
 156 returns:: a calculated value
 157
 158 discussion::
 159 you can enter a more in-depth discussion about this method here...
 160 this is a good place to put example code.
 161
 162 method:: bar
 163 another class method, etc..
 164
 165 SUBSECTION:: Special class methods
 166 method:: hello
 167 this is a method in a subsection of class methods..
 168
 169 INSTANCEMETHODS::
 170 private:: init, anotherPrivateMethod
 171
 172 method:: zoo
 173 here goes a description of the instance method zoo
 174 argument:: x
 175 here goes a description of argument x of method zoo
 176 argument:: y
 177 here goes a description of argument y of method zoo
 178
 179 EXAMPLES::
 180
 181 An example of how to use this and that:
 182 code::
 183 ...insert code here...
 184 \::
 185
 186 Another example:
 187 code::
 188 ...insert code here...
 189 \::
 190 ::
 191
 192 section:: Categories
 193 Try to find good categories for the doc you are writing/converting. If a suitable category already exists, you should use that. See the link::Browse##Document Browser:: (auto-generated) for existing categories.
 194
 195 For UGens, you should use the existing categories like UGens>Filter>Nonlinear. View the current categories like this:
 196 code::
 197 Ball.categories
 198 ::
 199 Or the directory layout if categories was not set.
 200
 201 For other documents, you could base it on the old directory layout, or come up with better ones. like Scheduling, Sequencing, Patterns, Streams, Server, etc..
 202
 203 Documents can exist in multiple categories, and also have hierarchical categories, like Sequencing>Patterns.
 204
 205 section:: Cross-document linking
 206 To link another document, use code:: link\::Path/To/Document\:: :: where the path is relative to code::SCDoc.helpTargetDir:: and the document filename is with no extension. Example:
 207 code::
 208 Also take a look at link::Classes/SinOsc:: and link::Reference/Literals::
 209 ::
 210 subsection:: Methods
 211 To link to a specific class method, append code::#*methodName:: or to an instance method, append code::#-methodName:: :
 212 code::
 213 Also take a look at the play method of link::Classes/Function#-play::
 214 ::
 215 This will render as link::Classes/Function#-play::
 216
 217 For generic methods documented outside of instancemethods or classmethods (like the generic link::Reference/play:: document), use a dot (.) as prefix instead of * or -.
 218
 219 The special link::Overviews/Methods:: overview is dynamic and allows a specific method to be shown by appending code::#name:: where name is the name of the method:
 220 code::
 221 For all implementations of play, see link::Overviews/Methods#play::
 222 ::
 223
 224 section:: Making the document findable by Search
 225 The link::Search:: page can match on document title/classname, summary, methods documented with code::method\::::, and categories.
 226 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:
 227 code::
 228 keyword:: someKeyWords
 229 ::
 230
 231 section:: Extensions
 232 subsection:: Quarks and extensions
 233 Each extension should have their own HelpSource folder with files that should be included in the help system.
 234 It's recommended that each Quark provides a Quarks/TheQuark.schelp file with categories "Quarks", that explains what the quark is and does.
 235
 236 Example file layout:
 237 code::
 238 MyQuark/HelpSource/Quarks/MyQuark.schelp
 239 MyQuark/HelpSource/Classes/MyClass1.schelp
 240 MyQuark/HelpSource/Classes/MyClass2.schelp
 241 MyQuark/HelpSource/Guides/MyGuide.schelp
 242 MyQuark/HelpSource/Guides/MyPicture.png
 243 MyQuark/MyClass1.sc
 244 MyQuark/MyClass2.sc
 245 ::
 246
 247 In the Quark directory file, set code::\helpdoc:: to the path relative to teletype::HelpSource:: and without the teletype::.schelp:: extension. Example: code::\helpdoc: "Quarks/MyQuark"::
 248
 249 subsection:: Method extensions
 250 An extension that adds methods to existing classes should document these in code::Classes/TheClass.ext.schelp::, only including the relevant bits (no title, summary, categories, etc..)
 251
 252 Example: Classes/String.ext.schelp
 253 code::
 254 INSTANCEMETHODS::
 255
 256 subsection:: Extensions by SCDoc
 257
 258 method:: stripWhiteSpace
 259 strips whitespace at the beginning and end of the string
 260 returns:: the stripped string
 261 ::
 262
 263 The contents are inserted into the right spot (section, subsection, etc).
 264 It works for all kind of sections, for example one can add a subsection to code::DESCRIPTION\:::: with additional information, or add another top-level section, etc.
 265