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

On Mon, Aug 12, 2013 at 12:48 AM, Lawrence Woodman
<lwoodman at vlifesystems.com> 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?

Packages do not have documentation, but collections inside of packages
may have documentation.

However, if you have a single collection package, then the info file
is for both the package and the collection metadata.

>     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?

Given the above, you don't separate them, because packages just don't have any.

>     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?

If you go to your user documentation root, such as with "raco docs" or
the Help menu in DrRacket, then it should show up in the ToC.

Jay

>
> 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
>



-- 
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://faculty.cs.byu.edu/~jay

"The glory of God is Intelligence" - D&C 93