Update docs for 0.14 tag (#118)

[mehaase]

Flesh out some missing pydocs, clean up the introduction, and make
the examples more common wsproto idioms.

[Kriechi]

Thanks! This looks great! 👍 🎉

[mehaase]

The lint build failed but it failed on lines I didn't change. Is this a blocker?

[Kriechi]

Mhm I re-ran the job - it still fails. Might be an newer linter / updates rules?
There are only 3 errors - and they don't look particularly problematic to fix - would you mind taking a look?

[mehaase]

I took a look but I'm not sure how to fix any of the errors. I'll paste here so we can discuss:

example/synchronous_client.py
  Line: 10
    pylint: import-error / Unable to import 'wsproto'

example/synchronous_server.py
  Line: 11
    pylint: import-error / Unable to import 'wsproto'

These two seem to be a configuration issue, like a bad $PYTHONPATH or $PWD. I'm not sure where that stuff is configured.

wsproto/__init__.py
  Line: 25
    pylint: syntax-error / misplaced type annotation (<unknown>, line 25)

The error refers to these lines in the constructor:

 # type: (ConnectionType) -> None
 self.client = connection_type is ConnectionType.CLIENT

I don't have any experience with type hints. Is that even valid way to type hint? It looks like a hint for a function but the field is a bool? I'm totally lost.

[pgjones]

Looks great, I'd be happy to merge as is, but I think you should remove the type information in the docstrings as #116 adds them in a way that can be verified.

[pgjones]

Regarding the linting issues, the wsproto/init.py line is removed in #116, it could also be removed here to pass the build.

I'm not sure we need to run pylint on the examples and I'm confused why these appear now?

[Kriechi]

I might have jumped the gun by merging #116 - and now we have a few conflicts here.. sorry 😄
@mehaase would you mind taking a look at resolving them?

The linting errors are not a blocker - we can fix (disable) them, after merging this PR.

[mehaase]

@Kriechi I just rebased this branch so it can merge into master.

I noticed that master has some new type annotations and so the pydocs are redundant in some places with the type annotations. Here's an example from wsproto/__init__.py:

    def send(self, event: Event) -> bytes:
        """
        Generate network data for the specified event.

        When you want to communicate with a WebSocket peer, you should construct
        an event and pass it to this method. This method will return the bytes
        that you should send to the peer.

        :param wsproto.events.Event event: The event to generate data for
        :returns bytes: The data to send to the peer
        """
        data = b""
        if self.connection is None:
            data += self.handshake.send(event)
            self.connection = self.handshake.connection
        else:
            data += self.connection.send(event)
        return data

The type of the event argument is included as both a type hint and a pydoc. I would eliminate the redundancy by removing the pydoc, but it seems Sphinx will only create links for types in the pydoc. It won't link to a type in a type hint. Here's a picture of the rendered Sphinx docs:

It looks like there is a Sphinx plugin that might render type hints better, but I haven't ever used it before. It seems like a big enough change to warrant opening a separate issue.

[Kriechi]

I don't mind the redundancy... at least for me, I'm still mostly looking at docstrings to figure out the expected types. Type hints have not been absorbed that deeply into my brain yet 😄

[pgjones]

I think the sphinx plugin is worth using and including (I'm hoping it works). Without it I would worry that the docstrings and type hints naturally diverge and add confusion over time.