Allow to generate page fragments

[hhugo]

In particular, it would be useful to integrate odoc a bit into existing designs such as http://ocsigen.org/js_of_ocaml/dev/manual/overview

[dbuenzli]

The css support is already here, see odoc support-files --whithout-theme and odoc html --theme-uri. I thought we already had an issue tracking generating a page fragment rather than a full page but I can't find it so this is it.

[hhugo]

It is #327 ?

[dbuenzli]

Not really. If you look at the sources of current pages like this one everything it already cleanly in its own div, #327 is just a request to have a better page structure.

One current slight problem though is the toplevel class named content on the div that needs fixing and be replaced by odoc for better stylesheet isolation/composition this is discussed in #298.

I think the simplest here would be to simply add a --fragment option to odoc html. The effect of that option would be the following:

1. Rather than generating the files with the .html suffix it generates the files with the suffix .htmlf (or .inc or .txt or .frag.html).
2. These files are exactly those that are generated now (in particular links) except only the current toplevel div is in there.

Now the build system (or the php script :-) of your website can simply read each of the $PATH.htmlf files and generate a corresponding $PATH.html file with your website chrome added.

Note that are other proposals floating around in the treasure trove of ideas that this issue tracker is... E.g. json output or this #121 issue. I personally think as a first good step all that should be closed and simply the above be implemented, I'm sure it will already go a long way for most "website chrome adding" needs.

[dbuenzli]

@hhugo what do you think about the proposed scheme ? This option could then also be added to odig odoc. I suspect it should not be too hard so I could try to squeeze this in along with #298 for the next release.

[trefis]

The --fragment proposal sounds very reasonable (and useful) to me.

I have no opinion on the CSS content →odoc renaming.

[dbuenzli]

I have no opinion on the CSS content →odoc renaming.

It's a class so we can have both, I'll just PR to add the odoc class along side the content.

Someone has a strong opinion on the file extension ? I think I'll go with .frag.html so that the files remain recognized as markup by various tooling (editors etc.).

[trefis]

I suspect it should not be too hard so I could try to squeeze this in along with #298 for the next release.

That would be neat!

I think I'll go with .frag.html so that the files remain recognized as markup by various tooling (editors etc.).

Sounds good to me.

[dbuenzli]

Sorry I don't have the time® to work on this right now®. But it seems we have a design and a motivated individual :-)

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.