search

SublimeText / sublime_lib

Utility library for frequently used functionality in Sublime Text and convenience functions or classes
https://sublimetext.github.io/sublime_lib
MIT License
52 stars 4 forks source link

Include type hints in documentation #137

Open FichteFoll opened 4 years ago

FichteFoll commented 4 years ago

The issue mentioned in https://github.com/SublimeText/sublime_lib/issues/118#issuecomment-499098498 for improving type hint rendering through sphinx has been closed (https://github.com/sphinx-doc/sphinx/issues/5868). From my understanding, this should allow us to add type hints to the documentation without the rendering problems that had been encountered before.

Thom1729 commented 4 years ago

After experimenting with the improved type hint output, I have come to the conclusion that it's still awful. But probably not totally unworkable.

FichteFoll commented 4 years ago

Do you happen to have a screenshot with example rendering? Or do you know of another project using typehints in sphinx?

Thom1729 commented 4 years ago

The default rendering isn't any different, but I've used the new markup to make some basic improvements:

snip

In the type-annotations-in-docs branch, I've used a heavier weight for the parameter name, and there shouldn't be line breaks within a parameter. It's still an awful mess on longer signatures, though:

snip2

I'm experimenting with various ways of cleaning that up. It's difficult because the new markup isn't very granular and the classes are very generic.

There are also bugs; for instance, a lot of functions have the wrong arguments displayed because the function is decorated and Sphinx doesn't respect functool.wraps. The workaround on their issue tracker is to monkey-patch functools.wraps, but I think it could be done less terribly.