[racket] Generating docs for gh-pages

From: Matthew Butterick (mb at mbtype.com)
Date: Sat May 10 20:04:16 EDT 2014

Also, for others who want to attempt the gh-pages clone technique, you need a slightly different command for single-page vs. multi-page Scribble docs.

Multi-page documentation can be generated like this:

scribble --dest-name doc --htmls +m --redirect-main http://docs.racket-lang.org/ path/to/your-main-scribble-source.scrbl

Whereas single-page documentation needs a couple extra settings so the resulting file will go into the 'doc' directory correctly:

scribble --dest doc --dest-name index --html +m --redirect-main http://docs.racket-lang.org/ path/to/your-one-scribble-source.scrbl 


Now using this technique on my three main Racket repos:

http://github.com/mbutterick/hyphenate (single)
http://github.com/mbutterick/txexpr (single)
http://github.com/mbutterick/pollen (multi)




On May 10, 2014, at 4:55 PM, Matthew Butterick <mb at mbtype.com> wrote:

> At the top of your Scribble sources, instead of this:
> 
> (for-label "../../ralist.rkt")
> 
> Refer to your package like this:
> 
> (for-label data/ralist)
> 
> 
> 
> 
> On May 10, 2014, at 3:28 PM, David Van Horn <dvanhorn at cs.umd.edu> wrote:
> 
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>> 
>> I'm trying to follow the directions Matthew Butterick gave for
>> generating scribble docs to push to a gh-pages branch:
>> 
>> http://lists.racket-lang.org/users/archive/2014-May/062339.html
>> 
>> I'm doing this for my ralist package:
>> 
>> https://github.com/dvanhorn/ralist
>> 
>> If I'm in the root directory of a clean checkout of the master branch
>> of that code, I can successfully run `raco pkg install' with no errors
>> or warnings.  The installed docs for ralist all look good.
>> 
>> Then when I try to build the docs for gh-pages, I run:
>> 
>> $ scribble --dest-name doc --htmls +m --redirect-main \
>> http://docs.racket-lang.org/ data/ralist/scribblings/main.scrbl
>> [Output to doc/index.html]
>> Warning: some cross references may be broken due to undefined tags:
>> (dep ((collects #"data" #"ralist.rkt") list-ref/set))
>> (dep ((collects #"data" #"ralist.rkt") in-list))
>> (dep ((collects #"data" #"ralist.rkt") list-update))
>> ...
>> 
>> and all of the references to names defined in this package are broken.
>> 
>> Can someone point me in the right direction?  This is on
>> 6.0.1.8--2014-05-10(fa68b57d/d).
>> 
>> Thanks,
>> David
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG/MacGPG2 v2.0.22 (Darwin)
>> 
>> iQIcBAEBAgAGBQJTbqgCAAoJEIVEqZR2RxA8oxYP/iL9MWdSYc9Wx9mqWdvBR3+r
>> QmH6R09YLyBJd7OmYd5yZToQV3DlOM4+KMtp4sNCqAGo+70sgK0Qchkqmn5VtUHD
>> LrpVfSe5GFOLDzkW1svJoZ/5zwNHPhecskSwigotpd0A9BfMynoeV+0IeMkeWulm
>> oXqdHi9WjoEHa3aC/OCNVWvo3al3VyvYHqL8ArIfL6RjmtWm5JYqtP/Ai9tQYZnB
>> veoA/h7ux4ed9f8VlzodTzx0JKiwNo0MYcdM6yaov9DUWJY9BXXfCGT4RRWZbLTd
>> xPQ4H7wjtmXKRwlZ9nwB8bPsmDqYo1F85nwZYX4PoGGDOAzx4/Jw4e+NjHQ8mFz1
>> GuPsUihfYEROA71L1NzhYV2e0rSqpm7K1BpfEy8/pPVzVSkdAm3dqfYH8tyKHLG+
>> kz9064x5rhJZSgyhhVGZ1tcGNvEu4J9qrVyiduNEc6ooNIds3/XlKqkD6WiGIXj5
>> U9xcuMUY5oAPdLnxrvD7p9vWlMl2AQbIgWjgjiu6aRnTbKvTGlpXjsJir/rYnLWx
>> YihFWvKl/hwDogg8Jv1F7ge0TK6L6AMYWYpTxKHiT54KZbGlaFIk7q2/w8KNFxHL
>> aPUszDUJ4CWtSTywsB+z5VHW+Hyq620ltNxxJOOJN+rPPoIdEJD00KTXg2RReVvR
>> NcU7y404PoyUE3DR5A/m
>> =oWZv
>> -----END PGP SIGNATURE-----
>> ____________________
>> Racket Users list:
>> http://lists.racket-lang.org/users
> 



Posted on the users mailing list.