Rudimentary support for assets

[trefis]

Context: #59 , #972

No support for referring to assets yet.
This only provides a way to get odoc to place them "in the right place" in the directory structure; so it's only marginally useful.

Current interface:

• children given to odoc compile can now be of the form asset-filename
• html-generate and html-targets commands now accept --asset FILE arguments, which are paired (based on filename) with the relevant child asset. Warnings are emitted for unknown and missing assets.
• files passed to html-generate through --asset are copied in the directory of their parent; would it be better to put them in an _assets subdirectory?

This is illustrated in test/pages/assets.t/run.t

[trefis]

I copied what was done for `SourcePage here, but honestly it looks weird.

[panglesd]

Is it the anchor = "" which is bothering you?

For some reason, "no anchor" is represented as "empty anchor". The type Url.t is even defined as Anchor.t. See any identifier which is a page, and thus has no anchor (Page, LeafPage, Root, ...)

So that's correct, but I agree it would look better if the anchor field was an option.

[trefis]

Is it the anchor = "" which is bothering you?

No, it's that we're getting a url to the parent of the asset, not the asset itself.

[panglesd]

Indeed, that's a bug, thanks for spotting it! It was not harmful because we only call Path.from_identifier on the `SourcePage variant, never Anchor.from_identifier.

Suggested change

	| { iv = `AssetFile (p, _name); _ } ->
	let page = Path.from_identifier p in
	Ok { page; kind = `File; anchor = "" }
	| { iv = `AssetFile _; _ } as p ->
	let page = Path.from_identifier p in
	Ok { page; kind = `File; anchor = "" }

Could you correct SourcePage and SourceDir as well?

[trefis]

I wondered if this should have been a fatal error, since I didn't know how to make it be one I managed to convince myself that it shouldn't be.

[panglesd]

I think odoc tries to avoid failing too badly in case of errors.

So I don't think it should be a hard failure, but that should not stop processing the other assets (see above)

[panglesd]

Nice!
I'm not sure why assets could not be children of compilation unit. But that should not be a too restrictive restriction, so I'm happy with it!
The only thing I would like to see changed is the non-handling of other assets in case of a missing asset.

[panglesd]

Is it the anchor = "" which is bothering you?

For some reason, "no anchor" is represented as "empty anchor". The type Url.t is even defined as Anchor.t. See any identifier which is a page, and thus has no anchor (Page, LeafPage, Root, ...)

So that's correct, but I agree it would look better if the anchor field was an option.

[panglesd]

I think odoc tries to avoid failing too badly in case of errors.

So I don't think it should be a hard failure, but that should not stop processing the other assets (see above)

[panglesd]

Also, there are compatibility issues that would need to be taken care of...

[dbuenzli]

What's the story from a user and driver (say odig which works out of installs) perspective ?

[trefis]

What's the story from a user and driver (say odig which works out of installs) perspective ?

I guess that's still open?
In the absence of references to / lookup for assets it would indeed be best if the various drivers used the same convention for picking the parents of their asset, but this PR isn't prescriptive in any way in that regard.

I do hope we can add references to assets in the not too distant future to make this question disappear, in the meantime my intuition is that right now the easiest is probably to use the "package root" as parent of the assets.

Does that somewhat answer your question, or did I totally miss your point?

[dbuenzli]

In the absence of references to / lookup for assets it would indeed be best if the various drivers used the same convention for picking the parents of their asset, but this PR isn't prescriptive in any way in that regard.

And yet that's what we need. It was already decided to not prescribe anything for the parent/child relationship and as I suggested at that the time that's not a good idea. We could have had perfectly self-described documents but are moving away from that more and more.

Look at what happend with upstream not prescribing anything for libraries: eco-system mess. Now odoc is perpetuating this.

[trefis]

It was already decided to not prescribe anything for the parent/child relationship and as I suggested at that the time that's not a good idea. We could have had perfectly self-described documents but are moving away from that more and more.

I get your point. However, after years of being away from odoc and having not been involved in this decision, I just came back for this "small" PR.
I do not plan to try and argue against decisions which have been made years ago, and certainly not in a PR like this one.

That being said:

• I hope this PR will still be beneficial to you, and to everyone else
• while odoc itself isn't prescriptive, other tools can and will be; in particular dune (and probably odig) and we are the ones who will write the behavior there, so if you have a precise proposal/request now is still a good time to make it known (or repeat it).

[panglesd]

I agree that the decision to make odoc more prescriptive is out of the scope of this PR, which just adds support for assets in a way that conforms to the current state of odoc.

The code looks good, let's merge, thanks @trefis!

[dbuenzli]

• while odoc itself isn't prescriptive, other tools can and will be; in particular dune (and probably odig) and we are the ones who will write the behavior there, so if you have a precise proposal/request now is still a good time to make it known (or repeat it).

This has been written for ages here and it's mentioned in #59. Interacting with this project remains as frustrating as ever I have to say.