Automatically generated API docs would be nice

[smheidrich]

Is your feature request related to a problem? Please describe. As far as I can tell, there are no automatically generated API docs and users are instead advised to have a look at the source code themselves. E.g. the docs on refactorings suggest:

Have a look at the rope.refactor package and its sub-modules.

Needless to say, this is not very convenient.

Describe the solution you'd like It would be nice if there were auto-generated API docs for Rope's public interface.

Describe alternatives you've considered

• Leave things as they are: People have a needlessly hard time using this library.
• Add more hand-written docs: It's an option but probably much more effort than auto-generation.

Additional context None.

[smheidrich]

I've had a look at how to best go about this for this project specifically. Here are my findings so far:

Option 1: autosummary

Sphinx's own autosummary extension has been able to generate docs recursively since 2020, but unfortunately, making it generate "complete" docs for each method rather than just one-line summaries still requires some template hacking which I'm not a fan of.

Option 2: sphinx-autoapi

The 3rd party sphinx-autoapi extension works better with only minimal configuration.

Problem 2.1: Inconsistent docstring markup languages

One problem I see (not the fault of sphinx-autoapi) is that this project's docstrings are a bit inconsistent with respect to what markup language they're written in: Sometimes `single backticks` are used for inline code (like in Markdown), other times ``double backticks`` like in ReST (the ratio of their occurrences is roughly 4:1 in favor of single backticks). But single backticks also make sense in Sphinx's ReST flavor e.g. when the default_role is set (usually to any), because then they represent a cross-reference.

Option 2.1.1: Ignore warnings for now

This issue shouldn't be a showstopper because all it does is cause a lot of warnings to be printed during the docs build, but the result still looks just fine (references that can't be found render the same as proper references, except they're not clickable).

Option 2.1.2: Replace ` → `` in most docstrings

Still, ideally, to get rid of all warnings, we'd have to replace a lot of inline code like `some code` or `some_param` in the docstrings by ``some code`` and ``some_param`` (the latter is annoying because this wouldn't be an issue if Sphinx allowed parameters as cross-reference targets; I tried to add the 3rd party sphinx-paramlinks extension to help with this, but it doesn't seem to work on parameter docs generated by sphinx-autoapi...).

Option 2.1.3: Use sphinx-autodoc2 to interpret docstrings as Markdown

Another option to circumvent the ReST docs vs semi-Markdown docstrings issue might be to use sphinx-autodoc2 which does allow configuring docstrings to be interpreted as Markdown.

But then we run into the opposite issue for all those places where double backticks (and other ReST features like :: blocks, of which there are a couple) were used, which don't look good at all when rendered as Markdown.

So I'd say 2.1.2 might be the lesser evil.

Option 3: Ditch Sphinx for something more modern

Just for completeness's sake, a lot of projects use MkDocs rather than Sphinx nowadays, with tools like mkdocstrings for their API docs. But I don't think that's worth it for Rope and it wouldn't solve the issues mentioned above anyway.