Generate argument/return types from type hints #10

I added the sphinx-autodoc-typehints module, which uses typehint
information to label argument types and return types, plus hyperlinks
those types. The result is much more readable and usable documentation.
There is unfortunately a bug with Python 3.7.5 dataclasses and type
annotations that produces some warnings during builds, but this should
be resolved in 3.7.6 (as well as 3.8.1).

Author: mehaase

docs/changelog.rst

@@ -0,0 +1,12 @@
+Changelog
+=========
+
+0.3.0
+-----
+
+- **Backwards compatibility break:** The CDP API avoids shadowing Python
+  built-ins. For example, an argument called ``id`` in CDP will be renamed to
+  ``id_`` in this library. Other common names include ``type_`` and
+  ``format_``.
+- The documentation has been improved to be faster to load and navigate.
+- Better handling of the "deprecated" and "experimental" flags.

docs/conf.py

@@ -29,6 +29,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
     'sphinx_rtd_theme',
 ]
 

docs/getting_started.rst

@@ -185,6 +185,8 @@ types. These types can improve autocompletion and also allow you to type check
 your own code that uses PyCDP.
 
 
+.. _getting-started-commands:
+
 Commands
 --------
 
@@ -303,10 +305,10 @@ convention transparently for you.
 Events
 ------
 
-While each command elicits a single response, the CDP protocol provides _events_
+While each command elicits a single response, the CDP protocol provides *events*
 as a mechanism for the browser to send information to the client that is not
-necessarily tied to a single command/response pair. Here's an example of a CDP
-event definition:
+tied to a single command/response pair. Here's an example of a CDP event
+definition:
 
 .. code-block:: json
 

docs/index.rst

@@ -13,9 +13,11 @@ Python wrappers for Chrome DevTools Protocol (CDP).
    getting_started
    api
    develop
+   changelog
 
-Indices and tables
-==================
+
+Indices
+=======
 
 * :ref:`genindex`
 * :ref:`modindex`

generator/generate.py

@@ -848,22 +848,48 @@ def generate_sphinx(self) -> str:
         docs += f'.. module:: cdp.{self.module}\n\n'
         docs += '* Types_\n* Commands_\n* Events_\n\n'
 
-        docs += 'Types\n-----\n'
-        docs += '\nGenerally you do not need to instantiate CDP types ' \
-            'yourself. Instead, the API creates objects for you as return ' \
-            'values from commands, and then you can use those objects as ' \
-            'arguments to other commands.\n'
+        docs += 'Types\n-----\n\n'
+        if self.types:
+            docs += dedent('''\
+                Generally, you do not need to instantiate CDP types
+                yourself. Instead, the API creates objects for you as return
+                values from commands, and then you can use those objects as
+                arguments to other commands.
+            ''')
+        else:
+            docs += '*There are no types in this module.*\n'
         for type in self.types:
             docs += f'\n.. autoclass:: {type.id}\n'
             docs += '      :members:\n'
             docs += '      :undoc-members:\n'
             docs += '      :exclude-members: from_json, to_json\n'
 
-        docs += '\nCommands\n--------\n'
+        docs += '\nCommands\n--------\n\n'
+        if self.commands:
+            docs += dedent('''\
+                Each command is a generator function. The return
+                type ``Generator[x, y, z]`` indicates that the generator
+                *yields* arguments of type ``x``, it must be resumed with
+                an argument of type ``y``, and it returns type ``z``. In
+                this library, types ``x`` and ``y`` are the same for all
+                commands, and ``z`` is the return type you should pay attention
+                to. For more information, see
+                :ref:`Getting Started: Commands <getting-started-commands>`.
+            ''')
+        else:
+            docs += '*There are no types in this module.*\n'
         for command in sorted(self.commands, key=operator.attrgetter('py_name')):
             docs += f'\n.. autofunction:: {command.py_name}\n'
 
-        docs += '\nEvents\n------\n'
+        docs += '\nEvents\n------\n\n'
+        if self.events:
+            docs += dedent('''\
+                Generally, you do not need to instantiate CDP events
+                yourself. Instead, the API creates events for you and then
+                you use the event\'s attributes.
+            ''')
+        else:
+            docs += '*There are no events in this module.*\n'
         for event in self.events:
             docs += f'\n.. autoclass:: {event.py_name}\n'
             docs += '      :members:\n'

requirements.txt

@@ -4,5 +4,6 @@ inflection
 mypy
 pytest
 sphinx
+sphinx-autodoc-typehints
 sphinx-rtd-theme
-twine
+twine