search

ocaml / ocaml.org

The official OCaml website.
https://ocaml.org
Other
155 stars 312 forks source link

Anchors don't work on packages READMEs #523

Open tmattio opened 2 years ago

tmattio commented 2 years ago

e.g. clicking https://ocaml.org/p/cohttp/5.0.0#dealing-with-redirects 1 in the TOC doesn’t work.

Reported by @mro at https://discuss.ocaml.org/t/anchors-missing-on-ocaml-org-p/10137

koonwen commented 2 years ago

Can I take this issue?

tmattio commented 2 years ago

Sure @koonwen, a PR for this would be welcome!

I didn't have a look yet, but at first glance, that could quickly become a rabbit hole.. Don't hesitate if you need any pointers or help on this.

koonwen commented 2 years ago

From what I understand, the reason why the anchors don't work is because the sections that we want to jump to are missing its corresponding tag.

I'm thinking that the fix for this would also require a validation pass over the HTML body to ensure that the tags that the TOCs refer to contain the tag. This could potentially cause a slowdown because we now need to add a parsing step dynamically after the READMEs are fetched.

What do you think?

tmattio commented 2 years ago

the reason why the anchors don't work is because the sections that we want to jump to are missing its corresponding tag

Are these working on the GitHub README? If yes, is it because GitHub is generating them or because there are on the README? If GitHub is generating them, we can do the same in the documentation pipeline: https://github.com/ocaml-doc/voodoo. This way we wouldn't have to add these dynamically.

koonwen commented 2 years ago

Yup Github is generating them.

Just to clarify what you mean and our the site fetches pages from. Our site fetches pages built by this documentation CI repo https://github.com/ocurrent/ocaml-docs-ci which internally uses voodoo to generate the docs. So I should be adding the validation and tag generation to https://github.com/ocaml-doc/voodoo?

Also I couldn't figure out the domain where the documentation is being hosted and the default url sends me a 403 error. It'll be nice to have so that I can see what's being built https://github.com/ocaml/ocaml.org/blob/8bb54ee7164ac7502da4172a1a92e1e8a4cd035f/src/ocamlorg_package/lib/config.ml#L6-L8

tmattio commented 2 years ago

Just to clarify what you mean and our the site fetches pages from. Our site fetches pages built by this documentation CI repo https://github.com/ocurrent/ocaml-docs-ci which internally uses voodoo to generate the docs. So I should be adding the validation and tag generation to https://github.com/ocaml-doc/voodoo?

Right! That's what I was suggesting 🙂

Also I couldn't figure out the domain where the documentation is being hosted and the default url sends me a 403 error.

Try accessing a file directly. To get the URL of a file in the docs server, you can take the target in the ocaml.org URL and append it to the https://docs-data.ocaml.org/live/ URL. So for instance, the raw documentation for this page https://ocaml.org/p/alcotest/1.6.0/doc/Alcotest/index.html can be found at https://docs-data.ocaml.org/live/p/alcotest/1.6.0/doc/Alcotest/index.html.

The README can also be accessed from the docs pipeline. Nothing links to it from the documentation of the packages, but to use the package given as an example in the description of the issue, you can find the README here: https://ocaml.org/p/cohttp/5.0.0/doc/README.md.html and on the docs server here: https://docs-data.ocaml.org/live/p/cohttp/5.0.0/doc/README.md.html

koonwen commented 2 years ago

HI @tmattio, I'm gonna need a few more hints 😬. I think my understanding how the docs are hosted is unclear so I can't figure out where to add the anchor support.

I've been looking through https://github.com/ocaml-doc/voodoo but I can't seem to find where the repos README are being processed. It looks like it only generates the module documentation? I also tried to look into https://github.com/ocurrent/ocaml-docs-ci to find where the README's might be fetched but I'm having trouble understanding how that pipeline works. Could you give me some pointers about how the docs hosting works?