[racket] How to document a package and access its documentation

Which version of Racket are you using?


With v5.3.6, I ran

 git clone https://github.com/LawrenceWoodman/xdgbasedir_rkt
 raco pkg install --name xdgbasedir --link xdgbasedir_rkt
 raco docs

and I see a "xdgbasedir" document. Note that `raco docs' opens my
user-specific documentation (since the default package scope is "user"
insteda of installation-wide), which means that it opened (on Mac OS
X):

  /Users/mflatt/Library/Racket/5.3.6/doc/index.html

while the documentation for "xdgbasedir" was rendered to

  ..../xdgbasedir_rkt/xdgbasedir/doc/xdgbasedir/index.html


With v5.90.x, you'll need to add

 (define collection 'multi)

to the package-level "info.rkt", since the default for package is now
single-collection.


At Mon, 12 Aug 2013 07:48:38 +0100, Lawrence Woodman wrote:
> Hello,
> 
> I'm a little confused with regard to how to document packages and 
> collections
> within them, and how to access that documentation when installing a package.
> 
> I have been working on a package:
> https://pkg.racket-lang.org/info/xdgbasedir
> 
> Which has the repository hosted on github:
>      https://github.com/LawrenceWoodman/xdgbasedir_rkt
> 
> When the package above was on PLaneT I could easily create scribblings 
> for it,
> point to them from the info.rkt and view those rendered docs on-line.
> However, with the package system, even though I have kept the info.rkt and
> scribblings under the collection, I can't see a straightforward way of 
> accessing
> that rendered documentation.  I'm also finding that when raco setup is being
> called as part of the installation of a package that it is complaining 
> that info.rkt has
> no info for scribblings, but the package management metadata doesn't say 
> that the
> manager uses the scribblings def.
> http://docs.racket-lang.org/pkg/metadata.html
> 
> So I have a few questions:
>      i. Should I put a scribblings entry in the package's info.rkt?
>      ii. If I do put a scribblings entry in the package's info.rkt, how 
> should I separate
>         the documentation between the package and the collection? i.e. 
> Should
>         I have a scribblings entry for each collection's info.rkt and 
> one for the package's
>         as well?
>      iii. How can I access the rendered documentation, without having to 
> manually
>          navigate to the directory the package was installed in and find 
> the doc/
>          directory?
> 
> Thanks
> 
> 
> Lawrence Woodman
> 
> 
> -- 
> vLife Systems Ltd
> Registered Office: The Meridian, 4 Copthall House, Station Square, Coventry, 
> CV1 2FL
> Registered in England and Wales No. 06477649
> http://vlifesystems.com
> 
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users