From 89ca0c26ce1d56ace45776bd7e083e447b0e8f48 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 23 Nov 2014 10:48:16 -0700 Subject: [PATCH] add `setup/materialize-user-docs` and related `raco setup` flags The new library provides a way to force a user-specific documentation etry point into existence. Normally, that would happen when a package with documentation is installed in user scope. After the entry point exists, then it sticks around even if all user-scope packages are removed. In some cases, it may be useful to force the entry point into existence as if packages had been installed and removed. (This might be useful for avoiding a quarantine on installed documentation files on Mac OS X, or a trampoline might be better.) --- .../racket-doc/scribblings/raco/setup.scrbl | 42 +++++++++++++++++-- pkgs/racket-pkgs/racket-index/info.rkt | 2 + .../setup/materialize-user-docs.rkt | 14 +++++++ .../racket-index/setup/scribble.rkt | 16 ++++--- racket/collects/setup/option.rkt | 1 + racket/collects/setup/setup-cmdline.rkt | 2 + racket/collects/setup/setup-core.rkt | 2 +- racket/collects/setup/setup.rkt | 3 ++ 8 files changed, 71 insertions(+), 11 deletions(-) create mode 100644 pkgs/racket-pkgs/racket-index/setup/materialize-user-docs.rkt diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl index c36ed59d80..338b7846d9 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl @@ -215,6 +215,10 @@ flags: @item{@DFlag{avoid-main} --- refrain from any setup actions that affect the installation, as opposed to user-specific actions.} + @item{@DFlag{force-user-docs} --- when building documentation, create + a user-specific documentation entry point even if it has the same + content as the main installation.} + ]} @item{Selecting parallelism and other build modes: @itemize[ @@ -277,9 +281,10 @@ collections during an install: @commandline{env PLT_SETUP_OPTIONS="-j 1" make install} -@history[#:changed "1.2" @elem{Added the @DFlag{pkgs}, +@history[#:changed "6.1" @elem{Added the @DFlag{pkgs}, @DFlag{check-pkg-deps}, and - @DFlag{fail-fast} flags.}] + @DFlag{fail-fast} flags.} + #:changed "6.1.1" @elem{Added the @DFlag{force-user-docs} flag.}] @; ------------------------------------------------------------------------ @@ -742,6 +747,7 @@ Optional @filepath{info.rkt} fields trigger additional actions by [#:avoid-main? avoid-main? any/c #f] [#:make-docs? make-docs? any/c #t] [#:make-doc-index? make-doc-index? any/c #f] + [#:force-user-docs? force-user-docs? any/c #f] [#:clean? clean? any/c #f] [#:tidy? tidy? any/c #f] [#:jobs jobs exact-nonnegative-integer? #f] @@ -770,10 +776,14 @@ Runs @exec{raco setup} with various options: @item{@racket[make-docs?] --- if @racket[#f], disables any documentation-specific setup actions} - @item{@racket[make-doc-index?] --- if @racket[#t], builds + @item{@racket[make-doc-index?] --- if true, builds documentation index collections in addition to @racket[collections], assuming that documentation is built} + @item{@racket[force-user-docs?] --- if true, then when building + documentation, create a user-specific documentation entry point + even if it has the same content as the installation} + @item{@racket[clean?] --- if true, enables cleaning mode instead of setup mode} @item{@racket[tidy?] --- if true, enables global tidying of @@ -792,7 +802,11 @@ Runs @exec{raco setup} with various options: ] The result is @racket[#t] if @exec{raco setup} completes without error, -@racket[#f] otherwise.} +@racket[#f] otherwise. + +@history[#:changed "6.1" @elem{Added the @racket[fail-fast?] argument.} + #:changed "6.1.1" @elem{Added the @racket[force-user-docs?] argument.}]} + @subsection{@exec{raco setup} Unit} @@ -1637,3 +1651,23 @@ the regexp matches @racket[(path->string sys-lib-subpath)], Like @racket[load-xref], but automatically find all cross-reference files for manuals that have been installed with @exec{raco setup}.} + +@; ------------------------------------------------------------------------ + +@section[#:tag "materialize-user-docs"]{API for Materializing User-Specific Documentation} + +@defmodule[setup/materialize-user-docs] + +@history[#:added "1.1"] + +@defproc[(materialize-user-docs [on-setup ((-> boolean?) -> any) (lambda (setup) (setup))]) + void?]{ + +Checks whether a user-specific documentation entry point already +exists with @racket[(find-user-doc-dir)], and if not, runs @exec{raco +setup} in a mode that will create the entry point (to have the same +content as the installation's documentation entry point.) + +The run of @exec{raco setup} is packaged in a thunk that is provided to +@racket[on-setup], which can adjust the current output and error ports +as appropriate and check the thunk's result for success.} diff --git a/pkgs/racket-pkgs/racket-index/info.rkt b/pkgs/racket-pkgs/racket-index/info.rkt index c7b9826422..e7cc090b93 100644 --- a/pkgs/racket-pkgs/racket-index/info.rkt +++ b/pkgs/racket-pkgs/racket-index/info.rkt @@ -11,6 +11,8 @@ (define pkg-authors '(eli jay matthias mflatt robby ryanc samth)) +(define version "1.1") + ;; We need to be able to re-render this documentation even in ;; binary mode, since that's how we list new documentation: (define binary-keep-files '("scribblings" diff --git a/pkgs/racket-pkgs/racket-index/setup/materialize-user-docs.rkt b/pkgs/racket-pkgs/racket-index/setup/materialize-user-docs.rkt new file mode 100644 index 0000000000..39515442dd --- /dev/null +++ b/pkgs/racket-pkgs/racket-index/setup/materialize-user-docs.rkt @@ -0,0 +1,14 @@ +#lang racket/base +(require setup/setup + setup/dirs) + +(provide materialize-user-docs) + +(define (materialize-user-docs [wrap-setup (lambda (t) (t))]) + (unless (file-exists? (build-path (find-user-doc-dir) "index.html")) + (wrap-setup + (lambda () + (setup #:avoid-main? #t + #:make-doc-index? #t + #:force-user-docs? #t))) + (void))) diff --git a/pkgs/racket-pkgs/racket-index/setup/scribble.rkt b/pkgs/racket-pkgs/racket-index/setup/scribble.rkt index 2ea94dee6d..8ff32d1194 100644 --- a/pkgs/racket-pkgs/racket-index/setup/scribble.rkt +++ b/pkgs/racket-pkgs/racket-index/setup/scribble.rkt @@ -89,11 +89,13 @@ (define (info