What do y’all use to render your API docs in Sphinx?
I’m nearly ready to just give up and use ReDoc/Swagger/etc, but I’d prefer something that integrates with the existing docs. But I just spent an hour poking at sphinxcontrib-openapi and its OpenAPI v3 support is just very patchy and sad …
I think I basically want the interface of sphinxcontrib-openapi (render the docs by way of sphinx directive, so that you can e.g. only render some endpoints), but the visuals of something like ReDoc (pretty, column layout) without its sidebar, and neither sphinxcontrib-openapi nor sphinxcontrib-redoc are doing this.
I really don’t want to build my own OpenAPI renderer …
I think I might be building a monster that renders one OpenAPI spec file from the API definition, then uses the ReDoc CLI to split the file up into separate endpoint files, and then use something like a custom sphinx tag (… okay, currently .. raw:) to render the file.
And then a ton of custom CSS to make the ReDoc sidebar disappear and make everything else render in styles compatible with the rest of the docs.
Nothing about this is good.
@rixx if it works, it is a good start. Sie is better than perfect :-) 👍👍
@rixx right. Saw the whole thread. Is effort so far online anywhere?
@carlton nah, I decided to be sad and just throw a lot of CSS at ReDoc. I really dislike the trend towards single-page API docs, and I think my previous page-per-resource was better, but it’s not worth the extra effort. So lots of CSS + some JS to hack section headings into my Sphinx sidebar has got to suffice. meh.
🐘 (er/ihm)