Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: scdoc_jit

This branch is 27 commits ahead, 5909 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

..
Failed to load latest commit information.
osx
README
SCDoc.sc
SCDocParser.sc
SCDocRenderer.sc
extForSCDoc.sc
integration_plan.txt

README

SuperCollider documentation system
==================================

USAGE
-----
To render and generate all docs:

SCDoc.updateAll;

Or, if you want to run it without the GUI progress window:

SCDoc.updateAll(gui:false);

NOTE: This may take a couple of minutes the first time.

After this, all rendered HTML help will be in SCDoc.helpTargetDir,
which defaults to "~/share/SuperCollider/Help" on Linux
and "~/Application Support/SuperCollider/Help" on OSX.
The folder is automagically created for you.

See these generated helpfiles for more info about ScDoc:

- Help/Reference/SCDocSyntax.html
- Help/Guides/WritingHelp.html
- Help/Classes/SCDoc.html
- Help/Classes/SCDocParser.html
- Help/Classes/SCDocRenderer.html

TODO
----
* integration with main sc distro: See integration_plan.txt

* the class-source links for classes in classLibraryDir won't work on OSX since the SuperCollider folder can be put anywhere..
fix: keep a softlink in helpTargetDir/SCClassLibrary pointing to the correct location. The pre-rendered docs would sit in the same folder as the app, so we would then have SCClassLibrary -> ../SCClassLibrary and it would work wherever the user puts the SuperCollider folder. 
In renderHTML, replace reference to thisProcess.classLibraryDir with baseDir+/+"SCClassLibrary".
In initHelpTargetDir, rewrite this link to point to the current value of thisProcess.platform.classLibraryDir.

* cross-platform: check all uses of systemCmd. move to Platform class? Some stuff are not possible on windows, use cygwin or similar?

* Handle methods added by extensions
Documenting added methods could be done in files named ClassName.ext.
before we render each class, we need to find all ClassName.ext files and merge their parsed node tree with the current class.
We should probably find these files first and keep their full paths in a dictionary with classname as key.
note that they should *add* to classmethods and instancemethods instead of creating new sections for these..

VALIDATION
----------
* better error handling in parser on bogus input, etc..

* Some tags should only be allowed once. like class, title, related, categories, summary, description, examples..
Also, they should only occur in the root node.

* private:: must come before any other method

* force class reference filename to be equal to class name, and located in Classes/, and using class:: instead of title::

* check method argument names (and order?). it's ok to skip arguments though..

* warn on nameless sections, subsections and methods

* make sure ## and || only happens inside lists/tables

PARSER BUGS
-----------
* this doesn't work as it should:

    modalrangetag:: blah blah blah
    blah blah blah blah blah
    blah blah ::

* this doesn't work as it should:

    hello

    soft::there::

* tags after each other doesn't work, like returns::link::hello::
perhaps hard to fix without taking into account if the tag needs closing or not?
for example, what does this mean: code::foo::link::bar::

* using \::. doesn't work, needs a space: \:: .
also sometimes non-letters after :: doesn't work as expected, like "(link::hello::)"

IDEAS AND IMPROVEMENTS
----------------------
* redirect classes doesn't show up in methods search, of course.. it would be nice if they did!
  let the class renderer add [(Meta_)thisClassName, methodName] to a special list that we append in SCDoc.collectAllMethods.
  Also we need to archive this to file somehow, and handle deletion/additions etc.. not a simple task :/
  Or, just maintain a dictionary of redirected classes -> redirecting class?
  in method search and index: if class is in this dict, replace with (or add) redirecting class.
  Or/and, let redirected classes have a link to the redirecting class?
  
  Also, if a class has implemented *doesNotUnderstand then maybe we should ignore if method was not found in renderer?
  for stuff like Scale..

* make a SCDoc.makeClassTemplate(class,outputfile) that fills in the title, categories if existing, method and argument names, etc..

* instead of showing "(extension)" only for classes, do it for any document that was located in an extension directory.
pass a flag to recurseHelpSource call in findExtHelp, and let updateFile return the doc map entry so we can set installed=\extension,
or pass the flag to updateFile and then to addToDocMap?
also add a check and warning for when a class file location and doc location is not the same in regards of extension or not?

* description for categories? HelpSource/category_descriptions, example:
  Server>Abstractions: Client-side classes representing server-side stuff
  show in header and category browser/overview..
  extensions should be able to add such descriptions too, but not overwrite existing descriptions?

* handle formula:: tag. generate a hash hexstring for use as filename, HelpSource/formulas/xxxxxxxx.png
The renderer would render formula:: by displaying that image if it exists, if not and if LaTeX is installed, convert formula to image first. if LaTeX not installed and image don't exist, show the latex code. (use img alt text?) 

* comments (* like this? *)

* shortcuts for links to method in class? methodlink::Node#-set:: renders as Node-set

* render binary op methods differently? like ArrayedCollections ++
we don't want it to display as "++ (aCollection)" do we? rather "++ aCollection" or "this ++ that" or something..
binary ops only uses chars from this list: !@%&*-+=|<>?/

Something went wrong with that request. Please try again.