Which interfaces would be useful for reStructuredText output?

[jonahbeckford]

I would like to know what would be necessary to generate reST from odoc.

1. I believe if odoc just does the compile phase (ie. generate .odoc files) and if I could read those files, I may be able to create a driver that generated reST (.rst) files. I can't seem to find which module to use to read the .odoc files. Which module does the reading?

2. I am not considering the linking phase because Sphinx will be used to tie together references. But it would mean I would need to visit each odoc reference and translate it into a Sphinx reference.

3. An alternative is using the modules that convert .cmti/.cmt/.cmi into the odoc internal representation. That would mean I couldn't take advantage of any caching done by odoc.

Has anybody else thought through what this involves?

(I am scoping what is necessary ... not making promises I'll do it! I also realize there are defunct tools to generate reST from OCaml but I think using odoc would be cleaner.)

Thanks.

[jonludlam]

The 'link' phase in odoc does a bit more than just linking things together, so I suspect you'd want to keep that bit of odoc. The links and anchors get turned into an internal type that's output-format independent, so you can probably generate sphinx-style references in a similar way to what we do for latex-style references.

You might want to take a look at #791 - it's an implementation of a new backend outputting markdown. One that targets rst would look pretty similiar I think, so it's probably a good place to figure out what would be required.

[jonahbeckford]

Thanks! That looks like a good starting place; the reST generator actually will be simpler than markdown because the reST only needs to output semantics not styling/formatting. (The styling is the responsibility of a decoupled Sphinx plugin that would live elsewhere).

I think this + Sphinx plug-in would be a good Outreachy project. https://discuss.ocaml.org/t/outreachy-december-2022/10336 . I can mentor unless one of you really wants to do it ... and can also maintain parts of it after the Outreachy sponsorship ends.

What do you think about getting a project for this?

[jonludlam]

Sounds like a great idea! It's possible to have more than one mentor on a project too :-)

[jonahbeckford]

Oh, totally forgot about co-mentoring! Would you be up for that? That way I could oversee more of the Sphinx/Python side (which I'm far far more familiar), and you and your fellow maintainers would not have any surprises on the odoc side.

[avsm]

@jonahbeckford @jonludlam the deadline for the mentor signup for the next round of Outreachy is tomorrow -- please do go ahead and sign up and I'll approve you and let me know if you have any problems. (cc @patricoferris). Your help is much appreciated! Once you sign up, you can submit the project proposal to the OCaml community project there.

[patricoferris]

Mentors can signup here: https://www.outreachy.org/communities/cfp/. The project submission deadline is the 29th September 2022 :))

[jonahbeckford]

Thanks @avsm and @patricoferris ! Paul-Elliot (Tarides) mentioned co-mentoring with me, but he's on vacation (and I don't know his GitHub handle). I'm going to delay the project for one cycle (is that 3 months?) until I've carved out some tasks that are more tractable. In particular I think the best way forward is to complete an embedding task (can we embed odoc into a larger site, and/or call it from another tool like Sphinx) and a rewriting task (can we write a PPX++ transformer of .mli so the community can easily experiment with adding functionality from doc tools like rst2html into odoc). (cc: @dbuenzli ) Neither of those tasks is straightforward today, but probably can be broken down into tasks more appropriate for Outreachy with some care over the next couple months. // Also I have some pause about the CoC, if that is coming into effect for Outreachy projects, which I'll post soon on the discuss site.

[dbuenzli]

I'm closing this since it's not an issue per se but a question. Feel free to continue the discussion.