Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Inline submodules, single-page HTML #5407

Closed
vicuna opened this issue Nov 24, 2011 · 8 comments
Closed

Inline submodules, single-page HTML #5407

vicuna opened this issue Nov 24, 2011 · 8 comments

Comments

@vicuna
Copy link

vicuna commented Nov 24, 2011

Original bug ID: 5407
Reporter: @mjambon
Assigned to: @zoggy
Status: assigned (set by @mjambon on 2012-03-14T22:45:36Z)
Resolution: reopened
Priority: normal
Severity: feature
Version: 3.12.1
Category: ocamldoc
Tags: html, ocamldoc
Monitored by: ronan.lehy@gmail.com tgazagna @ygrek @hcarty

Bug description

Would it be possible to have the two following options:

  1. keep the documentation of submodules on the same HTML page as the parent module (or compilation unit)

  2. produce a single HTML page instead of about one per source file (implies option (1))

Both would make search easier, especially when the modules or submodules are many and small.

Steps to reproduce

This is a very specific need. I suggest you develop your own custom generator for that (not much work: some methods to override).

@vicuna
Copy link
Author

vicuna commented Mar 14, 2012

Comment author: @mjambon

This doesn't strike me as particularly specific. How do you search for a given functionality within a library?

@vicuna
Copy link
Author

vicuna commented Mar 14, 2012

Comment author: @zoggy

grepping in mli files ?
Argot is what you're looking for: http://argot.x9c.fr/
It includes a local search capability, including searching on type and handling type isomorphism.

@vicuna
Copy link
Author

vicuna commented Mar 14, 2012

Comment author: @mjambon

While I appreciate the effort made by Argot, what I really want is native full-text search (Ctrl-f) that would be straightforward if ocamldoc-generated manuals came in a single-page variant, just like OMake's manual (http://omake.metaprl.org/manual/omake.html) atdgen's manual produced with Hevea (http://oss.wink.com/atdgen/atdgen-1.2.2/manual/atdgen-manual.html), the GNU Emacs manual (http://www.gnu.org/software/emacs/manual/emacs.html) and others.

I think it would benefit a large number of users without requiring any special-purpose search mechanism.

I don't completely exclude to do it myself, but it seems more easily done by the original author. Also the patch would need to be integrated in the official OCaml distribution.

@vicuna
Copy link
Author

vicuna commented Mar 20, 2012

Comment author: @zoggy

Another solution would be to generate a latex document, then use hevea to translate it to html :-)

I don't have time to develop this new generator, but if you create it, we can integrate it.

Here is how I see it:

  • It would be an extension of the default html generator, so you can develop it separately,
  • After integration, it would be choosen with a -one-html option.

You will have to handle, in links, the fact that everything is in one file. If it appears that it would be made easier if the Odoc_html.Naming module was a class, to change some methods, just tell me.

At last, interface to define a custom generator will change in next release, you can have a loot, for example, at
https://gitorious.org/ocamldoc-generators/ocamldoc-generators/blobs/master/odoc_todo.ml
(if you already use the ocaml-4.00 branch)

@vicuna
Copy link
Author

vicuna commented Mar 20, 2012

Comment author: @alainfrisch

We would also like to have the option to generate sub-modules on the same HTML page. (No real need on our side to generate everything on one big page.) A related topic: another option to "inline" included signatures.

@vicuna
Copy link
Author

vicuna commented May 7, 2013

Comment author: lebedev

Having an option, which allows to inline included signatures would be useful. See for example how Core containers are documented [1, 2], each module includes a private signature 'Creators', which is not accessible via the generated documentation.

@github-actions
Copy link

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

@github-actions github-actions bot added the Stale label May 15, 2020
@Drup
Copy link
Contributor

Drup commented May 21, 2020

As with the other ocamldoc feature requests, I suggest we close.

@nojb nojb closed this as completed May 21, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants