Would you be interested by a Sphinx in OCaml?

Community
, ,
1

Hello,

I’m coding a rst parser in ocaml (it works but needs a lot more testing and code cleaning, which is many weeks work. It is 10x faster than docutils) and I’d like to project myself in new endeavours using this parser. One of them is an equivalent of Sphinx in ocaml (with support of odoc and md).

Is it something you might use yourself or sphinx is already fine for your usage ? Do you have other ideas you feel more relevant ? Maybe I should only replace docutils by this parser + XML conversion (or another serde) ?

1 Like
2

I like the rst format a lot, and I would be happy to see an OCaml library for it. But I’m more interrested by hacking the format than a using a full end-user application. Two examples I have in mind right now:

  • Adding new directives
  • Create an alternative syntax for the roles which does not use the backtick system

If you provide a parser, I’ll be probably using the low-level library but having a new Sphinx is not a requirement for me.

3

Are you talking about a full re-implementation of Sphinx? That seems like a very ambitious project which you are of course free to set out and implement but maybe something like a Sphinx extension would get you to a working version faster?

4

Yes, a ocaml version of sphinx. At first the scope would be only HTML and no jinja/templating. Sphinx has some caching mechanisms that are worth reimplementing.
Also, no syntax highlighting for now.

Sphinx is great but slow (I suspect it’s bc of docutils but I didn’t benchmark yet).

There are features I would like to provide such as easier text indexing for search and a way to put placeholders to be generated later by user code in order to make it more backend-friendly.

5

cc @darrenldl and docfd

1 Like
6

I’m curious to learn more about what easier text indexing entails.

7
  • take into account the hierarchical nature of the documentation to suggest toctree non-leaf elements.
  • document-wise: score differently if header or emphasized, treat differently if normal text, literal block, admonition.
  • Use sphinx index (term to page) as an enhancer.
  • add corrective terms/boost via metadata (fields in rst). Allow human rating. Add click-through score.
  • incrementally update an index
  • allow a mix of fuzzy via finite state machine and a bag of n-gram approach.