We should generate and publish documentation for the Module API using Sphinx

[callahad]

Document the get_userinfo_by_id method in the ModuleApi.

The function was added in #9581, but there are no user-facing docs describing it.

[richvdh]

The documentation for methods in the ModuleApi is the docstring on those methods - are you saying we should document it elsewhere? Or that the docstring on that method is insufficient?

[reivilibre]

I presume Dan means it should appear in https://matrix-org.github.io/synapse/latest/modules.html.

However, I wonder if going forward it might be nicer to have docs that are generated from the docstrings — much like Doxygen, JavaDocs, Rust Docs, etc, to ensure they're kept in sync (both ways — when you use your IDE to view docs for things, you don't want to find out that you need to go visit our docs website instead..? But also, web-accessible docs are fairly nice for exploring).

[richvdh]

yeah, indeed. As a rule we don't document every method in the ModuleApi in that document, and I'm not entirely sure we should. Auto-generating docs from the docstrings might be nice. sphinx is the python equivalent of Doxygen and friends.

[reivilibre]

Should we refocus this issue to be about using Sphinx? It might also be a decent first issue

[callahad]

Ah, didn't look more broadly than seeing the PR in the 1.41 changelog, grepping doc/ and coming up empty handed. If we're not generally documenting the ModuleApi, then I guess this can be expended into a higher issue to autogen those docs.

[anoadragon453]

I'd be a little apprehensive to introduce another documentation backend into Synapse when we are already have mdbook, which can ingest any markdown input.

Would it not be more sensible to find a program to convert the ModuleApi python docstrings to a markdown file(s), which the existing documentation site can then display?

[richvdh]

Would it not be more sensible to find a program to convert the ModuleApi python docstrings to a markdown file(s) ...

If that's a thing that is doable, sure.

[anoadragon453]

gendoc looks to be such a program.

[reivilibre]

Would it not be more sensible to find a program to convert the ModuleApi python docstrings to a markdown file(s), which the existing documentation site can then display?

I'd be concerned about the readability. I don't think 'book'-style site generators have that much overlap with the 'code doc'-style generators (I also don't really know if Markdown can express the layout well enough without reverting to using HTML in Markdown).
I think there's something to be gained by using whatever is standard (or at least de facto standard) for code documentation within the language (for examples of this, see JavaDocs and cargo doc — every library ever (that I've ran into...) uses the same generator and it's all familiar). I don't recognise one for Python so this may be a moot point.

I don't mind the idea of generating Markdown first in principle, if the result can still be good.

That said, I don't personally think the output of gendoc is that readable, looking at the example they have in the repository (though I suppose that may be down to the process that converts it to HTML, too).

I also think that if you're going to add another tool anyway, does it really make much difference if it outputs HTML or Markdown first? The code documentation can sit in its own subdirectory in the web root and be otherwise independent.

That's just me though.