Open tmattio opened 2 years ago
Can I take this issue?
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.
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
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
What do you think?
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.
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
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
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?
Reported by @mro at https://discuss.ocaml.org/t/anchors-missing-on-ocaml-org-p/10137