Having trouble getting documentation to generate

[David Storrs]

Summary:  Documentation for a new module is not being generated when I would expect it to be and when I do it manually it ends up not linking basic Racket items.  I've done a lot of searching to figure it out and would appreciate some help.

Long version:

I published a module a few days ago called try-catch.  I have an announce email written up for it but I was waiting for the documentation to generate before sending.  It still hasn't generated so today I investigated.

First thing I did was make sure that raco was using the local copy for everything:

$ raco pkg remove try-catch

raco pkg remove: invalid `deps' specification
  specification: '("base" racket/format racket/string)

Weird. 

$ raco setup --check-pkg-deps try-catch

[...lots of stuff, no problems reported]

Okay, whatever.

$ raco pkg remove --force try-catch

Turn off the WiFi to be certain I don't get the package server version.

$ raco pkg install ./try-catch

Succeeds, claims that it is building the documentation, does not actually do so.  Ditto when I try

$ raco setup try-catch

When I manually run

$ cd try-catch/scribblings/ && scribble try-catch.scbl

I get the try-catch.html file as expected but racket/base functions such as with-handlers are not properly linked -- i.e. they appear in blue with a red line under them and are not links.

I do not get any missing dependencies when I run

My info.rkt file and try-catch.scrbl are both based on those from other modules I have that do work correctly.  I've checked the issues that were pointed out to me the last time I had to ask this question, I've been through the Racket documentation and through Beautiful Racket, and still not found the answer.  Any suggestions?

;; The info.rkt file

#lang info

(define collection "try-catch")
(define version "0.1")
(define deps '("base"
               "syntax-classes-lib"))

(define scribblings '(("scribblings/try-catch.scrbl" ())))

(define test-omit-paths '())
(define build-deps '("racket-doc"
                     "scribble-lib"
                     "rackunit-lib"
                     "sandbox-lib"))

;;----------

;;  The top lines from main.rkt to show the require:

#lang racket/base

(require (for-syntax racket/base
                     syntax/parse)
         racket/function)

;;----------

;; A stripped-down version of scribblings/try-catch.scrbl that demonstrates the failures

#lang scribble/manual

@(require (for-label racket)
          racket/sandbox
          scribble/example)

@defmodule[try-catch]

@(define eval
   (call-with-trusted-sandbox-configuration
    (lambda ()
      (parameterize ([sandbox-output 'string]
                     [sandbox-error-output 'string]
                     [sandbox-memory-limit 50])
(make-evaluator 'racket)))))

@itemlist[

@item{@racket[with-handlers], @racket[~a], @racketmodname[syntax-parse]}

]

@examples[
          #:eval eval
          #:label #f

    (require try-catch)
    (define err (defatalize (raise-arguments-error 'foo "failed")))
    err
    (try [(displayln "ok")])
]

[Ben Greenman]

On 9/28/21, David Storrs <david....@gmail.com> wrote:
> Summary: Documentation for a new module is not being generated when I
> would expect it to be and when I do it manually it ends up not linking
> basic Racket items. I've done a lot of searching to figure it out and
> would appreciate some help.

I cloned the try-catch repo (744f217), ran raco pkg install, and got a
nicely-rendered document. Log attached.

The only problem I saw is that `try` isn't linked. You can fix that by
adding a `(require (for-label try-catch))`.

> Long version:
>
> I published a module a few days ago called try-catch. I have an announce
> email written up for it but I was waiting for the documentation to generate
> before sending. It still hasn't generated so today I investigated.
>
> First thing I did was make sure that raco was using the local copy for
> everything:
>
> $ raco pkg remove try-catch
> raco pkg remove: invalid `deps' specification
> specification: '("base" racket/format racket/string)
>
> Weird.
>
> $ raco setup --check-pkg-deps try-catch
> [...lots of stuff, no problems reported]
>
> Okay, whatever.
>
> $ raco pkg remove --force try-catch
>
> Turn off the WiFi to be certain I don't get the package server version.
>
> $ raco pkg install ./try-catch
>
> Succeeds, claims that it is building the documentation, does not actually
> do so. Ditto when I try
>
> $ raco setup try-catch
>
> When I manually run
>
> $ cd try-catch/scribblings/ && scribble try-catch.scbl
>
> I get the try-catch.html file as expected but racket/base functions such as
> with-handlers are not properly linked -- i.e. they appear in blue with a
> red line under them and are not links.

That's normal. Scribble needs a few command-line flags to know where
to look for cross references (xrefs). I don't know the right flags
offhand.

> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/racket-users/CAE8gKoforSuxKVGwj2E_T-_HhLafaFipRGqERh6QUvyn6%2B9MUg%40mail.gmail.com.
>

[Sorawee Porncharoenwase]

When I manually run

$ cd try-catch/scribblings/ && scribble try-catch.scbl

I get the try-catch.html file as expected but racket/base functions such as with-handlers are not properly linked -- i.e. they appear in blue with a red line under them and are not links.

• As I understand, if you run scribble manually, you need to provide additional flags to make links work. I never remember what these flags are (perhaps +m?). But if you run Scribble via DrRacket, it should include these flags for you automatically.
• But you can also just view the already rendered docs via raco docs try-catch. No need to use scribble again — it’s already run as a part of raco setup. You can re-render it via raco setup. I like this way far better since the scribble command generates so many files in the source directory that I would need to add to .gitignore (I know --dest exists, but I usually forgot to provide it),  but raco setup generates the rendered doc either elsewhere or in doc directory, which can be added in .gitignore easily (actually it's already in gitignore if you use raco pkg new command).

[David Storrs]

*fists of rage*

I'm glad it worked for you, and that it works for me if I repeat your steps.  I have no idea why it wasn't working given that I was using the local copy of the git repository that is the source of what's on github.  Argh.

Regardless, thank you very much for your help.  I've fixed the (for-label try-catch), removed the test-more dependency, pushed it to github, and told the package server to rescan.  It says it will do that 1 minute from now, so hopefully it'll be good to go at that point.  I think documentation only gets generated once per day though, right?

Also, any ideas on why the remove fails?

$ raco pkg remove try-catch
raco pkg remove: invalid `deps' specification

  specification: '("base" racket/format racket/string)

That is not the deps specification from the info.rkt file so I don't know where it's getting that.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAFUu9R5%2B%3DbdPTXwrNgu1ZKfjzRSOYy03FmMAiRN%2Br2o3DEyoUA%40mail.gmail.com.

[Ben Greenman]

On 9/28/21, David Storrs <david....@gmail.com> wrote:
> *fists of rage*
>
> I'm glad it worked for you, and that it works for me if I repeat your
> steps. I have no idea why it wasn't working given that I was using the
> local copy of the git repository that is the source of what's on github.
> Argh.

Weird ... glad it's working.

> Regardless, thank you very much for your help. I've fixed the (for-label
> try-catch), removed the test-more dependency, pushed it to github, and told
> the package server to rescan. It says it will do that 1 minute from now,
> so hopefully it'll be good to go at that point. I think documentation only
> gets generated once per day though, right?
>
>
> Also, any ideas on why the remove fails?
>
> $ raco pkg remove try-catch
> raco pkg remove: invalid `deps' specification
> specification: '("base" racket/format racket/string)
>
> That is not the deps specification from the info.rkt file so I don't know
> where it's getting that.

Some package somewhere must have that bad info.rkt file.

A plain "raco setup" might be the quickest way to find the bad one.
That should print the name of every package as it goes through them.

Or, a "raco pkg remove -f try-catch" should work despite the invalid deps spec.

[David Storrs]

It did show them right up to the point where it bonked but did not show the name of the one it bonked on.  Fortunately, since you told me what the issue was I was able to find it with a simple:

$ find . -name official-racket -prune -o -name info.rkt -exec grep -l 'racket/format' \{} \;

Thanks!

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAFUu9R5%3DCL-_wfB52aG82Vg9y%2B9HKpQhxk_dX08ub5Ln948QGQ%40mail.gmail.com.

[Robby Findler]

I'm not quite following from the thread, but it sure sounds like there is a bug in raco setup (or similar) somewhere that isn't reporting an error properly. Is that the case?

Robby

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAE8gKoevcaM26JaaBYVZCORxsXJXVUO9zZNJYR2UPcH_94Rb8Q%40mail.gmail.com.

[Philip McGrath]

On Tue, Sep 28, 2021 at 3:30 PM Ben Greenman <benjamin...@gmail.com> wrote:

On 9/28/21, David Storrs <david....@gmail.com> wrote:
> $ raco pkg remove try-catch
> raco pkg remove: invalid `deps' specification
>   specification: '("base" racket/format racket/string)
>
> That is not the deps specification from the info.rkt file so I don't know
> where it's getting that.

Some package somewhere must have that bad info.rkt file.

I'm not sure exactly what `raco pkg` should do when it encounters such an error, but it probably shouldn't just leave you stuck with unwanted erroneous packages forever.

I haven't tried `raco setup` to look at its output, but one possible improvement would be for whatever code complains about the "invalid `deps' specification" to always report the invalid file's path.

-Philip

[Matthew Flatt]

At Wed, 29 Sep 2021 02:27:53 +0000, Philip McGrath wrote:
> I haven't tried `raco setup` to look at its output, but one possible
> improvement would be for whatever code complains about the "invalid `deps'
> specification" to always report the invalid file's path.

I've pushed that addition.

[David Storrs]

Thanks, Matthew.  Is this a "download Racket 8.2" thing or an "update from github" thing?

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/20210929075734.246%40sirmail.smtps.cs.utah.edu.

[Matthew Flatt]

At Wed, 29 Sep 2021 11:20:47 -0400, David Storrs wrote:
> On Wed, Sep 29, 2021 at 9:57 AM Matthew Flatt <mfl...@cs.utah.edu> wrote:
>
> > At Wed, 29 Sep 2021 02:27:53 +0000, Philip McGrath wrote:
> > > I haven't tried `raco setup` to look at its output, but one possible
> > > improvement would be for whatever code complains about the "invalid
> > `deps'
> > > specification" to always report the invalid file's path.
> >
> > I've pushed that addition.
> >
> >
> Thanks, Matthew. Is this a "download Racket 8.2" thing or an "update from
> github" thing?

The improvement is only in the GitHub repo right now. So, updating from
GitHub gets it now, it will also be part of the next round of
snapshots, and then it will be part of the upcoming v8.3 release.


Matthew

[David Storrs]

Cool, thanks.

[Siddhartha Kasivajhula]

Looks like the try-catch package docs still aren't showing up.

This might be a broader issue with the package index and docs, since I just renamed one of my packages that already had docs, and the docs now no longer exist on the package index (it says "this package needs documentation"). I think this is because the package now reflects as a new package and so runs afoul of whatever issue appears to be afflicting new arrivals.

I checked the "New Releases" section of the latest issue of Racket News to validate whether new packages are especially affected, and of the packages listed there, a majority of them include scribble docs that we can see listed in the package modules, but the docs show up for none of them:

https://pkgs.racket-lang.org/package/in-out-logged

https://pkgs.racket-lang.org/package/libansilove

https://pkgs.racket-lang.org/package/pprint-compact

https://pkgs.racket-lang.org/package/codepoint

https://pkgs.racket-lang.org/package/fmt

https://pkgs.racket-lang.org/package/pareto-frontier

https://pkgs.racket-lang.org/package/majordomo2

--

You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAE8gKoegBUGVbfmguydZwaVBWgrNOJWJ3CmxTvShROR4-dpvJw%40mail.gmail.com.

[Sorawee Porncharoenwase]

Here’s additional information: I uploaded pprint-compact on September 22. https://pkgs.racket-lang.org/ briefly shows the documentation for a few days. But after a package update around September 26, the website no longer lists the documentation. The doc is still actually available at https://docs.racket-lang.org/pprint-compact/.

The root cause seems to be how https://pkgs.racket-lang.org/pkgs-all.json.gz doesn’t have the doc data in the build/docs field.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CACQBWF%3DmjJAxAg6xbwfYTDQk8TnDhJyoTYhroxA1XW70CV67zg%40mail.gmail.com.

[Sorawee Porncharoenwase]

And while we are at the package website issue, can someone please take a look at my PR to fix the blank package bug (https://github.com/racket/pkg-index/pull/29)?

[Matthew Flatt]

I've adjusted pkgs.racket-lang.org to fix a problem with fetching the
pkg-build status from pkg-build.racket-lang.org. That is, packages were
being built and documentation was incorporated into
docs.racket-lang.org, but pkgs.racket-lang.org wasn't reflecting that.

(I didn't do more than try to fix this specific problem, though.)

At Fri, 8 Oct 2021 10:40:31 -0700, Siddhartha Kasivajhula wrote:
> Looks like the try-catch package docs still aren't showing up

> <https://pkgd.racket-lang.org/pkgn/package/try-catch>.

>
> This might be a broader issue with the package index and docs, since I just
> renamed one of my packages that already had docs, and the docs now no
> longer exist on the package index (it says "this package needs
> documentation"). I think this is because the package now reflects as a new
> package and so runs afoul of whatever issue appears to be afflicting new
> arrivals.
>
> I checked the "New Releases" section of the latest issue of Racket News

> <https://racket-news.com/2021/10/racket-news-issue-54.html#newreleases> to

> <https://groups.google.com/d/msgid/racket-users/CAE8gKoegBUGVbfmguydZwaVBWgrNOJW
> J3CmxTvShROR4-dpvJw%40mail.gmail.com?utm_medium=email&utm_source=footer>
> > .
> >