4.1 Getting Started with Documentation

Although the scribble command-line utility generates output from a Scribble document, documentation of Racket libraries is normally built by raco setup. This chapter emphasizes the raco setup approach, which more automatically supports links across documents.

See Getting Started for information on using the scribble command-line utility.

4.1.1 Setting Up Library Documentation

To document a collection or PLaneT package:

• Create a file in your collection or planet package with the file extension ".scrbl". Beware that the file name you choose will determine the output directory’s name. The remainder of these instructions assume that the file is called "manual.scrbl".

• Start "manual.scrbl" like this:

  #lang scribble/manual

  @title{My Library}

  Welcome to my documentation: @racket[(list 'testing 1 2 3)].

  The first line starts the file in “text” mode and selects the Racket manual output format. It also introduces bindings like title and racket for writing Racket documentation.

• Add the following entry to your collect or package’s "info.rkt":

    (define scribblings '(("manual.scrbl" ())))

  The () above is a list of options. When your document gets large enough that you want it split into multiple pages, add the 'multi-page option (omitting the quote, since the whole right-hand side of the definition is already quoted).

  If you do not already have an "info.rkt" module, here’s a suitable complete module:

  #lang setup/infotab

  (define scribblings '(("manual.scrbl" ())))

• Run raco setup to build your documentation. For a collection, optionally supply -l followed by the collection name to limit the build process to that collection. For a PLaneT package, optionally supply -P followed by the package information to limit the build process to that package.

• The generated documentation is normally "doc/manual/index.html" within the collection or PLaneT package directory. If the collection is in Racket’s main "collects" directory, however, then the documentation is generated as "manual/index.html" in the installation’s main "doc" directory.

4.1.2 Racket Typesetting and Hyperlinks

In the document source at the start of this chapter (Setting Up Library Documentation), the Racket expression (list 'testing 1 2 3) is typeset properly, but the list identifier is not hyperlinked to the usual definition. To cause list to be hyperlinked, add a require form like this:

@(require (for-label racket))

This require with for-label declaration introduces a document-time binding for each export of the racket module. When the document is built, the racket form detects the binding for list, and so it generates a reference to the specification of list. The setup process detects the reference, and it finds the matching specification in the existing documentation, and ultimately directs the hyperlink to that specification.

Hyperlinks based on for-label and racket are the preferred mechanism for linking to information outside of a single document. Such links require no information about where and how a binding is documented elsewhere:

#lang scribble/manual

@(require (for-label racket))

@title{My Library}

See also @racket[list].

The racket form typesets a Racket expression for inline text, so it ignores the source formatting of the expression. The racketblock form, in contrast, typesets inset Racket code, and it preserves the expression’s formatting from the document source.

#lang scribble/manual

@(require (for-label racket))

@title{My Library}

Some example Racket code:

@racketblock[

(define (nobody-understands-me what)

(list "When I think of all the"

what

"I've tried so hard to explain!"))

(nobody-understands-me "glorble snop")

]

4.1.3 Section Hyperlinks

A section declaration in a document can include a #:tag argument that declares a hyperlink-target tag. The secref function generates a hyperlink, using the section name as the text of the hyperlink. Use seclink to create a hyperlink with text other than the section title.

The following example illustrates section hyperlinks:

#lang scribble/manual

@(require (for-label racket))

@title{My Library}

Welcome to my documentation: @racket[(list 'testing 1 2 3)].

@table-of-contents[]

@section[#:tag "chickens"]{Philadelphia Chickens}

Dancing tonight!

@section{Reprise}

See @secref{chickens}.

Since the page is so short, the hyperlinks in the above example are more effective if you change the "info.rkt" file to add the 'multi-file flag:

  (define scribblings '(("manual.scrbl" (multi-page))))

A section can have a tag prefix that applies to all tags as seen from outside the section. Such a prefix is automatically given to each top-level document as processed by raco setup. Thus, referencing a section tag in a different document requires using a prefix, which is based on the target document’s main source file. The following example links to a section in the Racket reference manual:

#lang scribble/manual

@(require (for-label racket))

@(define ref-src

'(lib "scribblings/reference/reference.scrbl"))

@title{My Library}

See also @italic{@secref[#:doc ref-src]{pairs}}.

As mentioned in Racket Typesetting and Hyperlinks, however, cross-document references based on (require (for-label ....)) and racket are usually better than cross-document references using secref.

4.1.4 Defining Racket Bindings

Use defproc to document a procedure, defform to document a syntactic form, defstruct to document a structure type, etc. These forms provide consistent formatting of definitions, and they declare hyperlink targets for racket-based hyperlinks.

To document a my-helper procedure that is exported by "helper.rkt" in the "my-lib" collection that contains "manual.scrbl":

• Use (require (for-label "helper.rkt")) to import the binding information about the bindings of "helper.rkt" for use when typesetting identifiers. A relative reference "helper.rkt" works since it is relative to the documentation source.

• Add a @defmodule[my-lib/helper] declaration, which specifies the library that is being documented within the section. The defmodule form needs an absolute module name mylib/helper, instead of a relative reference "helper.rkt", since the module path given to defmodule appears verbatim in the generated documentation.

• Use defproc to document the procedure.

Adding these pieces to ""manual.scrbl"" gives us the following:

#lang scribble/manual

@(require (for-label racket

"helper.rkt"))

@title{My Library}

@defmodule[my-lib/helper]

@defproc[(my-helper [lst list?])

(listof

(not/c (one-of/c 'cow)))]{

Replaces each @racket['cow] in @racket[lst] with

@racket['aardvark].}

In defproc, a contract is specified with each argument to the procedure. In this example, the contract for the lst argument is list?, which is the contract for a list. After the closing parenthesis that ends the argument sequence, the contract of the result must be given; in this case, my-helper guarantees a result that is a list where none of the elements are 'cow.

Some things to notice in this example and the documentation that it generates:

• The list?, listof, etc. elements of contracts are hyperlinked to their documentation.

• The result contract is formatted in the generated documentation in the same way as in the source. That is, the source layout of contracts is preserved. (In this case, putting the contract all on one line would be better.)

• In the prose that documents my-helper, lst is automatically typeset in italic, matching the typesetting in the blue box. The racket form essentially knows that it’s used in the scope of a procedure with argument lst.

• If you hover the mouse pointer over my-helper, a popup reports that it is provided from my-lib/helper.

• If you use my-helper in any documentation now, as long as that documentation source also has a (require (for-label ....)) of "helper.rkt", then the reference is hyperlinked to the definition above.

See defproc*, defform, etc. for more information on forms to document Racket bindings.

4.1.5 Showing Racket Examples

The examples form from scribble/eval helps you generate examples in your documentation. Warning: the examples form is especially likely to change or be replaced.

To use examples, the procedures to document must be suitable for use at documentation time; in fact, examples uses bindings introduced into the document source by require. Thus, to generate examples using my-helper from the previous section, "helper.rkt" must be imported both via require-for-label and require:

#lang scribble/manual

@(require scribble/eval    ; <--- added

"helper.rkt"     ; <--- added

(for-label racket

"helper.rkt"))

@title{My Library}

@defmodule[my-lib/helper]{The @racketmodname[my-lib/helper]

module---now with extra cows!}

@defproc[(my-helper [lst list?])

(listof (not/c (one-of/c 'cow)))]{

Replaces each @racket['cow] in @racket[lst] with

@racket['aardvark].

@examples[

(my-helper '())

(my-helper '(cows such remarkable cows))

]}

4.1.6 Multi-Page Sections

Setting the 'multi-page option (see Section Hyperlinks) causes each top-level section of a document to be rendered as a separate HTML page.

To push sub-sections onto separate pages, use the 'toc style for the enclosing section (as started by title, section, subsection, etc.) and use local-table-of-contents to generate hyperlinks to the sub-sections.

Revising "cows.scrbl" from the previous section:

#lang scribble/manual

@title[#:style '(toc)]{Cows}

@local-table-of-contents[]

@section[#:tag "singing"]{Singing}

Wherever they go, it's a quite a show.

@section{Dancing}

See @secref["singing"].

To run this example, remember to change "info.rkt" to add the 'multi-page style. You may also want to add a call to table-of-contents in "manual.scrbl".

The difference between table-of-contents and local-table-of-contents is that the latter is ignored for Latex output.

When using local-table-of-contents, it often makes sense to include introductory text before the call of local-table-of-contents. When the introductory text is less important and when when local table of contents is short, putting the introductory text after the call of local-table-of-contents may be appropriate.