Coexisting Markdown and RST documentation

Julia docstrings are expected to be written in Markdown, but there are situations where it it may be useful to use other formats. E.g. the package GR is part of a larger project whose documentation seems to be made with Sphinx, using sources written in RST (cf. https://gr-framework.org). The documentation of GR’s high-level functions in Julia (https://gr-framework.org/julia-jlgr.html) uses the docstrings given in the source code, which are also written in RST to be consistent with the rest of the documentation.

As I commented some days ago, I am working on GRUtils, a package based on a module of GR to make it more “Julian”, and I wonder what should I do with the docstrings. One the one hand side I would like it to have docstrings that are nicely parsed by the tools provided by Julia (e.g. Documenter.jl), and this means rewriting them as Markdown. On the other hand, I would like to facilitate the production of documentation sources based on RST - as those of the original GR package -, with the same docstrings.

Is it possible to have both things? How can this be made?

3 Likes