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.)
This commit is contained in:
Matthew Flatt
parent
b2a919af40
commit
89ca0c26ce
|
|
@ -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.}
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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)))
|
||||
|
|
@ -89,11 +89,13 @@
|
|||
(define (info<? a b)
|
||||
(doc<? (info-doc a) (info-doc b)))
|
||||
|
||||
(define (filter-user-docs docs make-user?)
|
||||
(define (filter-user-docs docs make-user? always-user?)
|
||||
(cond ;; Specifically disabled user stuff, filter
|
||||
[(not make-user?) (filter main-doc? docs)]
|
||||
;; If we've built user-specific before, keep building
|
||||
[(file-exists? (build-path (find-user-doc-dir) "index.html")) docs]
|
||||
[(or always-user?
|
||||
(file-exists? (build-path (find-user-doc-dir) "index.html")))
|
||||
docs]
|
||||
;; Otherwise, see if we need it:
|
||||
[(ormap (lambda (doc)
|
||||
(not (or (doc-under-main? doc)
|
||||
|
|
@ -137,9 +139,9 @@
|
|||
program-name ; name of program that calls setup-scribblings
|
||||
only-dirs ; limits doc builds
|
||||
latex-dest ; if not #f, generate Latex output
|
||||
auto-start-doc? ; if #t, expands `only-dir' with [user-]start to
|
||||
; catch new docs
|
||||
auto-start-doc? ; if #t, expands `only-dir' with [user-]start to catch new docs
|
||||
make-user? ; are we making user stuff?
|
||||
always-user? ; make user-specific even if otherwise unneeded
|
||||
tidy? ; clean up, even beyond `only-dirs'
|
||||
avoid-main? ; avoid main collection, even for `tidy?'
|
||||
with-record-error ; catch & record exceptions
|
||||
|
|
@ -221,7 +223,8 @@
|
|||
(values k #t))]
|
||||
[infos (map get-info/full (map directory-record-path recs))])
|
||||
(filter-user-docs (append-map (get-docs main-dirs) infos recs)
|
||||
make-user?))
|
||||
make-user?
|
||||
always-user?))
|
||||
doc<?))
|
||||
(define-values (main-docs user-docs) (partition doc-under-main? docs))
|
||||
(define main-doc-exists? (ormap (lambda (d) (member 'main-doc-root (doc-flags d)))
|
||||
|
|
@ -272,7 +275,8 @@
|
|||
(and tidy? (not avoid-main?)))))
|
||||
(define auto-user? (and auto-start-doc?
|
||||
(or (ormap can-build*? user-docs)
|
||||
(and tidy? make-user?))))
|
||||
(and tidy? make-user?)
|
||||
always-user?)))
|
||||
(define (can-build**? doc) (can-build? only-dirs doc auto-main? auto-user?))
|
||||
|
||||
(unless latex-dest
|
||||
|
|
|
|||
|
|
@ -65,6 +65,7 @@
|
|||
(define-flag-param make-user #t)
|
||||
(define-flag-param make-planet #t)
|
||||
(define-flag-param avoid-main-installation #f)
|
||||
(define-flag-param force-user-docs #f)
|
||||
(define-flag-param make-tidy #f)
|
||||
(define-flag-param make-doc-index #f)
|
||||
(define-flag-param check-dependencies #t)
|
||||
|
|
|
|||
|
|
@ -107,6 +107,8 @@
|
|||
(add-flags '((make-planet #f)))]
|
||||
[("--avoid-main") "Do not make main-installation files"
|
||||
(add-flags '((avoid-main-installation #t)))]
|
||||
[("--force-user-docs") "User-specific documentation even if matching installation"
|
||||
(add-flags '((force-user-docs #t)))]
|
||||
#:help-labels
|
||||
" ------------------------------ modes ------------------------------ "
|
||||
#:once-each
|
||||
|
|
|
|||
|
|
@ -1260,7 +1260,7 @@
|
|||
(parallel-workers)
|
||||
name-str
|
||||
(if no-specific-collections? #f (map cc-path ccs-to-compile))
|
||||
latex-dest auto-start-doc? (make-user)
|
||||
latex-dest auto-start-doc? (make-user) (force-user-docs)
|
||||
(make-tidy) (avoid-main-installation)
|
||||
(lambda (what go alt) (record-error what "building docs" go alt))
|
||||
setup-printf))
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@
|
|||
#:clean? [clean? #f]
|
||||
#:tidy? [tidy? #f]
|
||||
#:avoid-main? [avoid-main? #f]
|
||||
#:force-user-docs? [force-user-docs? #f]
|
||||
#:jobs [parallel #f]
|
||||
#:fail-fast? [fail-fast? #f])
|
||||
(parameterize
|
||||
|
|
@ -47,6 +48,8 @@
|
|||
|
||||
[avoid-main-installation (if avoid-main? #t (avoid-main-installation))]
|
||||
|
||||
[force-user-docs (if force-user-docs? #t (force-user-docs))]
|
||||
|
||||
[fail-fast fail-fast?]
|
||||
|
||||
[clean (if clean? #t (clean))]
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user