Proposal: p6doc server

Motivation

The primary motivation for p6doc-server is to speed up and significantly expand the CLI p6doc tool, which currently pays the cost of EVAL-slurp-ing the same file over and over again. p6doc-server would hold this file in memory and respond to API calls by handing back serialized data structures.

This way all of the useful bits required for querying the docs (show all available options in the Language category, as one simple example) will be localized into a reusable core which could also be hooked into editors or an interactive web app driven by the p6doc-server API.

Potential Implementation

p6doc-server will be implemented as an HTTP server which responds to a REST API via JSON (initially). Serial formats should be pluggable, as should the transport mechanism.

Exploratory API

We currently have 'Language', 'Types', and 'Routines' as views on doc.perl6.org. So, starting with these, every path and sub path will respond to 'list', but I would also add a Modules "header", which would provide access to any Pod belonging to modules in your @*INC.

• /api/list

  • Language
  • Types
  • Routines
  • Modules

• /api/language/list

  • 5to6
  • about
  • .... (though of course they would be displayed with their pod titles rather than filenames)

• /api/language/5to6

  • ( returns the full pod for 5to6 )

• /api/language/5to6/list

  • ( returns a table of contents of 5to6, including API paths to append to /api/language/5to6/ )

(Where the "last" list should be provided is probably right here, at the file level. But it needn't be, if it would make sense to provide list-able sections.)

There should also be a search option, which would look something like /api/language/[5to6]/search/$term.

It would return different things according to a few param settings (Note that I am just trying to get my ideas out there for discussion, so please take these param names as preliminary):

• lines-in-snippet: return snippets with $n lines surrounding any term match
• match-sections: return the entire section of Pod which matches the term