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.
