[racket] Writing module documents

There are many good examples on PLaneT. For me, the 'best practice' depends
on the complexity of the collection I am documenting - e.g., a single module
or something more complex. My UUID package (
http://planet.racket-lang.org/display.ss?package=uuid.plt&owner=williams) is
a single module and I have a single uuid.scrbl file for the Scribble
documentation. My science collection (
http://planet.racket-lang.org/display.ss?package=science.plt&owner=williams)
has many modules and it has a scribblings directory (with an image
subdirectory) with a scrbl file for each chapter in the documentation - with
multi-page specified in the info.rkt file. All of my packages follow one or
the other of those formats. Others on the mailing list may have different
strategies that they follow.

If you put your collection on PLaneT (http://planet.racket-lang.org/), the
HTML files are automatically generated (in a planet-docs subdirectory) and
are available to the user from the search facility once they have been
downloaded - via an appropriate require form. [You can also view them
on-line. For example, the UUID package documentation is at
http://planet.racket-lang.org/package-source/williams/uuid.plt/1/2/planet-docs/uuid/index.htmland
the science collection documentation is at
http://planet.racket-lang.org/package-source/williams/science.plt/3/10/planet-docs/science/index.html.]


For more information, look at the PLaneT documentation (
http://docs.racket-lang.org/planet/index.html) or in the Help Desk. And,
browse the PLaneT packages for documentation styles you like and look at
their scrbl files.

Doug

On Sun, Dec 12, 2010 at 1:17 AM, Mark Carter <mcturra2000 at yahoo.co.uk>wrote:

> My personal module is coming together, and I would like to write some
> documentation for it. Scribble seems the way to go, but I don't really know
> how
> to tackle the problem. What's the best practise? Create a folder called
> scribblings and write scrbl files within it? Is there a way that the html
> is
> then autogenerated and available from the search facility of DrRacket?
>
>
>
>
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20101212/d9c0e735/attachment.html>