Unify docutils type annotations about sphinx HOT 11 CLOSED

i've created a PR to track the migration here - #12012

contributions (both to the PR and upstream in typeshed) very very welcome!

from sphinx.

Good idea! I am always frustrated because of how poor autocompletion is done with docutils on Pycharm so I'll be very happy if this can be merged upstream.

from sphinx.

I won't be there next week, and I don't think I'll have time for that today. But I'll do it by in two weeks (I will take time for that).

from sphinx.

Is the 'context' truly generic?

If you are talking about state transitions, like def blank(self, match, context, next_state):, then context is a list[str]

I'm not super familiar with the inner workings of the docutils statemachines

I am, I've been through it in excruciating detail, because I'm writing an RST parser as we speak 😉

This all looks great, thanks for all the work!
... although obviously it would be a million time easier, if we could just type docutils itself 😅

from sphinx.

Have started tweaking type annotations in typeshed, with a view to reach parity and then transition this repo to typeshed

python/typeshed#11468

from sphinx.

@sphinx-doc/triagers @sphinx-doc/developers @sphinx-doc/former-maintainers @picnixz

can I pretty please get a solid review of python/typeshed#11469?

It introduces a generic type argument to the docutils state machine to represent the context. That generic argument will propogate through into a massive number of docutils types so is a significant change. Before that happens I want to check this is correct!
I'm not super familiar with the inner workings of the docutils statemachines. Is the 'context' truly generic? what is its type?

from the docutils docs:

context: application-specific storage.

from sphinx.

@sphinx-doc/triagers @sphinx-doc/developers @sphinx-doc/former-maintainers @picnixz

can I pretty please get a solid review of python/typeshed#11469?

It introduces a generic type argument to the docutils state machine to represent the context. That generic argument will propogate through into a massive number of docutils types so is a significant change. Before that happens I want to check this is correct! I'm not super familiar with the inner workings of the docutils statemachines. Is the 'context' truly generic? what is its type?

from the docutils docs:

context: application-specific storage.

stand down!

I've postponed adding generics, even if they are technically correct. The decision is blocking progress and would have significant downstream impact.
I'll revisit in a separate PR and just type the context as Any for now

from sphinx.

If you are talking about state transitions, like def blank(self, match, context, next_state):, then context is a list[str]

I believe that's true of the rst-specific subclasses. Is it also true of the superclass? (I'll take your word for it)

from sphinx.

Ah thank you chris for helping here since I am travelling (I'm currently in a train). Could I ask you to help with the upstream PRs (I can come back later if there are some questions though it's been a while since I played with docutils)?

from sphinx.

Could I ask you to help with the upstream PRs

Okie, I will try to carve out some time for it 👍

from sphinx.

i'm proposing that #12012 be merged, warts and all so that all future improvements to typing are made against the community-supported typeshed docutils stubs

from sphinx.