[racket] extracting "docstrings" from documentation
Danny Yoo
racket/base. By documentation strings, I truly mean strings. Here's
the progress I'm making on this:
https://github.com/dyoo/extract-docstring
It's buggy still, and I'm working out the kinks.
The process I'm using to approach this is frankly a little insane, and
I would rather not go to the nuthouse for this. I'm using setup/xref
and scribble/xref to figure out the source line and anchor of a
binding. Next, I parse the HTML, grab at the element with the given
anchor name, and start sucking up HTML till I hit the next anchor.
I am web-scraping, and I know I should be ashamed of myself. But I do
not see any other mechanisms available to me at the moment. Have I
missed something obvious?
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/users
Matthew Flatt
question should be: What should Scribble provide?
Originally, I had in mind including docstring-like information in the
cross-reference output of a Scribble document. That approach would work
badly with the current implementation of cross-reference information,
however, because the information already takes too much memory. (On a
32-bit machine, around 20MB of DrRacket's initial footprint is
cross-reference information for installed documentation, and that cost
doubles when online check syntax is enabled.) Probably cross-reference
information should actually be in a database, instead of a serialized
hash table, but I haven't yet tried anything in that direction.
Any other ideas?
Robby Findler
to docs in the REPL?
Robby
Eli Barzilay
> I don't know that anything better is available right now, but maybe the
> question should be: What should Scribble provide?
>
> Originally, I had in mind including docstring-like information in the
> cross-reference output of a Scribble document. That approach would work
> badly with the current implementation of cross-reference information,
> however, because the information already takes too much memory. (On a
> 32-bit machine, around 20MB of DrRacket's initial footprint is
> cross-reference information for installed documentation, and that cost
> doubles when online check syntax is enabled.) Probably cross-reference
> information should actually be in a database, instead of a serialized
> hash table, but I haven't yet tried anything in that direction.
>
> Any other ideas?
IIUC (guessing that this is the usual use case for docstrings), then
the text renderer seems close enough -- maybe some extension for it
that
* ignores text that doesn't document a specific binding (and maybe
also description text that is too long for a short docstring),
* and instead of spitting out the texts into a file, will put them all
indexed in some way (either a file with some very simple info-style
markup or a db)
--
((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay:
http://barzilay.org/ Maze is Life!
Sam Tobin-Hochstadt
<ro...@eecs.northwestern.edu> wrote:
> What is the usecase for this information? Giving people quick access
> to docs in the REPL?
I would personally want it for tooltips etc in DrRacket, and also when
autocompleting identifiers. This is present in lots of existing IDEs
such as VS, Eclipse, etc. This video of Clojure in Emacs demos
something like that: http://vimeo.com/22798433 , which I think we
could definitely have in DrRacket.
--
sam th
sa...@ccs.neu.edu
Robby Findler
tooltips for identifiers.
Robby
Danny Yoo
> to docs in the REPL?
For my particular use case, I need to take slices of the documentation
and re-present them in a Scribble document.
Specifically: WeScheme has a subset of behavior of Racket. To document
WeScheme's API, I want to take the documentation of the forms in
Racket and inline them into my document.
I want to be able to say something like:
@copy-documentation[first 'racket/list]
@copy-documentation[second 'racket/list]
where "copy-documentation" is a hypothetical special form that splices
in the documentation associated to the given binding. That way, if
the original documentation changes, it's an easy matter for me to
replicate it. I really want to avoid the copy-and-paste issue.
Another case where this might be useful is in tutorial documentation,
where having the documentation of the forms inline with the rest of
the document can be a very important thing in terms of reducing the
number of indirect references.
Matthias Felleisen
That would be fantastic