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 <[email protected]>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 >
_________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/users
