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

ocamldoc does not generate HTML linkable IDs for modules #7635

Closed
vicuna opened this issue Sep 21, 2017 · 6 comments

Comments

Projects
None yet
2 participants
@vicuna
Copy link

commented Sep 21, 2017

Original bug ID: 7635
Reporter: @yawaramin
Assigned to: @Octachron
Status: resolved (set by @Octachron on 2017-09-30T21:25:53Z)
Resolution: fixed
Priority: normal
Severity: minor
Fixed in version: later
Category: ocamldoc
Tags: ocamldoc
Monitored by: @gasche

Bug description

ocamldoc does not generate span elements with linkable IDs when generating HTML documentation.

Steps to reproduce

If I have the following mli:

module A : sig end

type a

val a1 : a

And I run ocamldoc on it to produce HTML documentation, the HTML will contain linkable IDs (in span elements) for the latter two items, but not the first one, that is not for the module:

...

...

@vicuna

This comment has been minimized.

Copy link
Author

commented Sep 21, 2017

Comment author: @yawaramin

Sorry, forgot to mention how the module span looks like:

module

@vicuna

This comment has been minimized.

Copy link
Author

commented Sep 21, 2017

Comment author: @Octachron

It is true that submodule items are not given a specific id. However, submodules are fully expanded in a separate page ("Main.Submodule.html"), thus it is still possible to link to a specific submodule.

Do you have any example where it would make sense to link to "Main.html#MODULEA" rather than "Main.A.html"?

@vicuna

This comment has been minimized.

Copy link
Author

commented Sep 21, 2017

Comment author: @yawaramin

My goal is to allow generating a table of contents for each module doc page. E.g., for the module sig above, I would want to generate the following TOC:

(ul)
(li class="module")(a href="#MODULEA")A(/a)(/li)
(li class="type")(a href="#TYPEa")a(/a)(/li)
(li class="val")(a href="#VALa1")a1(/a)(/li)
(/ul)

(Using parens instead of angle brackets here because otherwise Mantis is trying to format as HTML. I would also include after the closing tag the first sentence of the item's doc comment, for ease of reference.)

To make this possible, it would be good to have that 'MODULEA' ID, e.g. Otherwise if the user clicked on types and values in the TOC they would be jumped down to the main documentation for the item, in the same page; but if they clicked on a module they would be jumped to another page, which would be confusing.

@vicuna

This comment has been minimized.

Copy link
Author

commented Sep 30, 2017

Comment author: @Octachron

See #1383 for a possible implementation.

@vicuna

This comment has been minimized.

Copy link
Author

commented Sep 30, 2017

Comment author: @Octachron

Fixed by merging the above PR in trunk.

@vicuna vicuna closed this Sep 30, 2017

@vicuna

This comment has been minimized.

Copy link
Author

commented Sep 30, 2017

Comment author: @yawaramin

@Octachron nice! I'm rebasing on this now, will send PR soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.