Re: Docstrings and literate programming (good practices?)

[Max Nikulin]

On 04/11/2022 10:03, Samuel Wales wrote:
> for example, you have a body of non-literate elisp code, and you have
> a manual.  it could be redundant to describe commands and what they do
> and their options, if the docstrings are good.

There is Sphinx in Python world that allows to combine guide pages with 
API docs extracted from source files: classes, functions, variables, 
modules (files). Some introduction and API reference may work well. I 
tried it, but without going deeper I did not manage to achieve the same 
quality as I saw for some packages at readthedocs.
https://www.sphinx-doc.org/en/master/

What I miss in texinfo is a feature similar to Intersphinx
https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx
To generate external references in HTML pages, an index file may be 
downloaded. As a result anchors in docs or function names are linked to 
proper files, anchors are formatted with section names as their description.

https://docs.python.org likely uses another tool, but the approach is 
often the same: general description and docstrings.

I think, Org manual published on the web site would benefit from links 
to HTML API reference generated from docstrings.

P.S. Pages generated by doxygen may be convenient as well. It is nice to 
have details related to functions and classes linked from overview, 
design description, a guide how this API should be used. Of course, it 
works only if such pages are written and added to doxygen config.