On May 18, 2012, at 8:47 AM, Uri Zarfaty wrote:
> Hi all,
>
> I've been trying to use scribble/srcdoc for in-source documentation, and have
> a couple of hopefully straightforward questions.
>
> 1) Is it possible to use scribble/eval examples in proc-doc/names? Trying
> this naively results in an undefined identifier error, presumably since the
> function binding was not introduced to the source file that defines it using
> a require.
>
> 2) Is it possible to use include-previously-extracted without requiring an
> additional file for provide-extracted (e.g. by having the provide-extracted
> in either the source or documentation file)?
>
> Answers that only work in 5.3 (e.g. using submodules) are fine. Thanks!
I created a provide-and-scribble macro parallel to Matthew's effort on srcdoc.
I stopped (not because I saw his, but because I have too many things to do at
once.)
My goal is to provide documentation for the HtDP teachpacks that always shows
at least one interaction with the documented function i.e. a use of
@interaction.
Here is the idea, sketched out:
;; provide-and-scribble.rkt
;; the macros
#lang at-exp racket
(require (for-syntax syntax/parse) scribble/manual scribble/eval racket/sandbox)
(provide
define-module-local-eval
provide-and-scribble
)
;;
---------------------------------------------------------------------------------------------------
(define-for-syntax add-sections #f)
(define-syntax (provide-and-scribble stx)
(syntax-parse stx #:literals (defproc)
[(provide-and-scribble (title (defproc (name args ...) range desc ...) ...)
...)
(define add-docs-and-provide
;;
**********************************************************************************
;; this needs something like a @defmodule[localname] but perhaps
;; this should be added when I require the doc submodule
;;
**********************************************************************************
#`((module+ doc (#,add-sections title (list (defproc (name args ...)
range desc ...) ...)))
...
(provide name ... ...)))
(cond
[add-sections add-docs-and-provide]
[else
(set! add-sections (syntax-local-introduce #'add-sections))
#`(begin
(module+ doc
(provide docs)
(define *sections '())
(define (#,add-sections stitle scontent)
(set! *sections (cons (list stitle scontent) *sections)))
(define (docs)
(reverse *sections)))
#,@add-docs-and-provide)])]))
;; (define-module-local-eval name-of-evaluator)
;; a make-base-eval whose namespace is initialized with the module where the
macro is used
(define-syntax-rule
(define-module-local-eval name)
(begin
(define-namespace-anchor ns)
(define name
(parameterize ([sandbox-namespace-specs (list (lambda ()
(namespace-anchor->namespace ns)))]
[sandbox-error-output 'string]
[sandbox-output 'string])
(make-base-eval)))))
---------------------------------------------------------------------------------------
;; provide-and-define.rkt
;; a sample library that uses provide-and-scribble with @interaction
#lang at-exp racket
(require "provide-and-scribble.rkt" scribble/manual scribble/eval)
(define-module-local-eval my-eval)
(define (f x) `(f ,x))
(define (g x) `(g ,x))
(define (h x) `(h ,x))
(provide-and-scribble
("Numbers"
@defproc[(f [x number?]) number?]{hello world @interaction[#:eval my-eval (f
10)]}
@defproc[(g [x number?]) number?]{hello world @interaction[#:eval my-eval (g
10)]}
)
("Strings"
@defproc[(h [x number?]) number?]{hello world @interaction[#:eval my-eval (h
"hello")]}
))
---------------------------------------------------------------------------------------
;; provide-and-test.scrbl
;; the scribble document that uses the docs
#lang scribble/manual
@(require (submod "provide-and-define.rkt" doc))
@(let loop ([s (docs)])
(cond
[(null? s) '()]
[else
(define-values (section-title stuff) (apply values (car s)))
(cons @section{@section-title}
(cons @stuff (loop (cdr s))))]))
____________________
Racket Users list:
http://lists.racket-lang.org/users
