brownplt / pyret-docs

The documentation for Pyret.
9 stars 18 forks source link

Docs search for "is-roughly" isn't useful #42

Closed jpolitz closed 4 years ago

jpolitz commented 6 years ago

There should be results for is-roughly:

image

jpolitz commented 6 years ago

(This isn't a problem with search; it's a problem with the docs, to be clear; @sorawee 's new feature just makes it easy to find missing docs!)

jpolitz commented 6 years ago

Ditto is-not:

image

sorawee commented 6 years ago

This will be difficult.

The missing results right now are generated with a custom function like this https://github.com/brownplt/pyret-docs/blob/master/src/lang/testing.scrbl#L11

But to make the result appears in the glossary page, some kind of tagging/indexing like this must be used. https://github.com/brownplt/pyret-docs/blob/master/scribble-api.rkt#L375

Anything that is documented with data-spec2, for example, won't be indexed because of the same reason (e.g., https://www.pyret.org/docs/latest/reactors.html#%28part._reactors_.Event%29 doesn't have an item in the glossary page.)

I think @blerner is the only one who knows how these indexing works and how to use them properly...

blerner commented 6 years ago

The main API to make index elements in Scribble is index: https://docs.racket-lang.org/scribble/base.html?q=make-index-element#%28def._%28%28lib._scribble%2Fbase..rkt%29._index%29%29, and which does some cleanup stuff and then calls make-index-element to produce the actual content that shows up in the page. You're free to call index wherever you'd like to add additional index items, and they'll just show up in the glossary automatically.

I baked the calls to make-index-element directly into type-spec because I didn't want the default cleanup behavior of index in these circumstances, and because type-spec defines a bunch of different names. I didn't add it to data-spec2 yet because I don't understand how that one works, or whether it's even the most current one to be used.

blerner commented 4 years ago

This seems to be fixed on horizon