RST doc strings?

[snunez1]

I like what you're doing here. A well thought out doc system is desperately needed in the CL ecosystem, rather than the dozen half-baked ones we have now.

As far as mark-up format, RST seems a richer choice than MD. Are there plans to implement MD and a Sphinx converter or domain? I'm aware of cl-domain, however its license isn't compatible with commercial use and anything GNU isn't an option for our projects.

[svetlyak40wt]

This can be done in case if you will implement something like https://40ants.com/commondoc-markdown/ but for converting reStructured Text to CommonDoc structures. CommonDoc is extensible and you can create new node types if you need.

However, for docstrings I don't see a reason to use more complex markup than markdown. All I need from reStructured Text and Sphinx for docstrings is automatic cross-links. But they are already working and with no additional syntax – you just mention a symbol in uppercase.

Probably some other rst features might be useful for longer documents, for example tables. And here at least two ways to implement them. You either have to write a rst -> commondoc converter, nor create special lisp syntax, to include new blocks in defsection body. For example, tables could look like this:

(defsection @readme (:title "Readme")
   "# Here is a description

    Some other text"

    (table :title "The demo numbers"
       (:header "Head 1" "Head 2" "Head 3")
       (:row 100 200 300))

   "And here we have subsequent paragraph of text continuing after the table.")

The latter approach is more flexible and you don't limited by reStructured Text's syntax. However, it will work only for block elements, not for inline.

[svetlyak40wt]

By the way, on what kind of projects are you working on?

[Symbolics]

This can be done in case if you will implement something like https://40ants.com/commondoc-markdown/ but for converting reStructured Text to CommonDoc structures. CommonDoc is extensible and you can create new node types if you need.

Ah, so you're using CommonDoc. I always thought Fernando Borretti was on the right track with codex. A shame that development stalled. He had the right idea, but it never seems to have gone beyond proof-of-concept.

Does your use of CommonDoc mean we can use the Scriba syntax for formatting doc strings?

[svetlyak40wt]

Common Doc is used internally to represent documentation nodes. So it should be more easy to add a Scriba syntax support. Right now I have no time and motivation to work on this myself.

However, if you would like to add this feature yourself, I'll show places there this can be hooked in.