opam-doc
opam-doc copied to clipboard
ocamllabs
Uris
Why did you choose http://ocaml-redesign.github.io/docs/opam/?package=async_core&module=Async_or_error instead of http://ocaml-redesign.github.io/docs/opam/async_core/Async_or_error/ ?
This is because there's a script that dynamically loads the documentation. Having static files would mean potentially generating hundreds of megabytes (or more) of documentation for (big) packages which use "include".
I'm fine having a script which expands the includes. But you can at least generate an entry page per package and per modules in that package (which seems a more natural naming convention than having to pass extra arguments to your global script).
I did something like this once and used a single script/page but generated subdirectories and symlinked each resource name in the subdirectory to the main page. The main page then introspected on the URL and loaded the appropriate panorama. It is also possible to prevent a full server round trip by using the HTML5 pushState API to change the URL without re-GET-ing the symlink.
I'm fine having a script which expands the includes. But you can at least generate an entry page per package and per modules in that package (which seems a more natural naming convention than having to pass extra arguments to your global script).
Oh, yeah, ok, I see. A quick hack for ocaml-redesign.github.io would be to generate some P/M/index.html that redirect to ../../?package=P&module=M.
Note that it is not very easy to have /package/module/submodule/... urls in the general case because a module can include a module which includes a module which adds a submodule etc.. Although we could easily add urls for all toplevel modules.
I don't think the "submodule/..." is very useful in practice. But having a direct links to package/ and package/module would be very useful.
To be more complete on the uri scheme. It would be nice if opam-doc generates overlay on top of an existing repository (as we plan to do in opam2web). eg. doc related to a given package should go in:
packages/name/name.version/
Would be trivial after that to integrate it with a local opam2web instance. @dsheets does it make sense ?
An overlay is a good idea if it has a consistent structure. Right now, we have 3 package repository structures:
opam:
packages/name.version/
opam2web:
packages/name/version/
new opam (?):
packages/name/name.version/
We should decide on one and harmonize across all the tools. I think the packages/name.version/ is unacceptable due to its lack of per-project path. This leaves the (new) opam2web convention and the (new) opam convention which both seem acceptable. I do wonder, why does new opam repeat the name in the project subdirectory? Is it to reuse the existing parsing logic? What happens if the name's unsync? It's also sorta long... :-P
Yes, the plan is to switch to packages/name/name.version/ once the final 1.1 is out. Regarding the "long" names, OPAM is looking for any files called packages/XX/YY/ZZ/name.version/opam to compute the available packages in the repository.
I think that I want to switch to urls of the form:
packages/name/name.version/docs/#Module.Submodule
Yes, this URI format is nice.
On 1 Nov 2013, at 15:18, Leo White [email protected] wrote:
I think that I want to switch to urls of the form:
packages/name/name.version/docs/#Module.Submodule
— Reply to this email directly or view it on GitHub.
I like this format.
What about "api" or "doc" instead of "docs"? I guess it depends on what else you see being hosted under the path and what siblings you foresee.