Merge pull request #259 from bluetech/doc-fixes

Minor doc improvements

Author: bluetech

README.rst

@@ -16,7 +16,7 @@ execnet: distributed Python deployment and communication
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/python/black
 
-.. _execnet: http://codespeak.net/execnet
+.. _execnet: https://execnet.readthedocs.io
 
 execnet_ provides carefully tested means to ad-hoc interact with Python
 interpreters across version, platform and network barriers.  It provides

doc/_templates/layout.html

@@ -18,16 +18,3 @@ <h1>execnet: Distributed Python deployment and communication</h1>
 </code>
 </div>
 {% endblock %}
-
-{% block footer %}
-{{ super() }}
-<script type="text/javascript">
-var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
-document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
-</script>
-<script type="text/javascript">
-try {
-var pageTracker = _gat._getTracker("UA-7597274-7");
-pageTracker._trackPageview();
-} catch(err) {}</script>
-{% endblock %}

doc/basics.rst

@@ -6,7 +6,7 @@ execnet ad-hoc instantiates local and remote Python interpreters.
 Each interpreter is accessible through a **Gateway** which manages
 code and data communication.  **Channels** allow to exchange
 data between the local and the remote end.  **Groups**
-help to manage creation and termination of sub interpreters.
+help to manage creation and termination of sub-interpreters.
 
 .. image:: _static/basic1.png
 
@@ -26,10 +26,10 @@ Here is an example which instantiates a simple Python subprocess::
 
     >>> gateway = execnet.makegateway()
 
-gateways allow to `remote execute code`_ and
+Gateways allow to `remote execute code`_ and
 `exchange data`_ bidirectionally.
 
-examples for valid gateway specifications
+Examples for valid gateway specifications
 -------------------------------------------
 
 * ``ssh=wyvern//python=python3.3//chdir=mycache`` specifies a Python3.3
@@ -82,15 +82,15 @@ in the instantiated subprocess-interpreter:
 .. automethod:: Gateway.remote_exec(source)
 
 It is allowed to pass a module object as source code
-in which case it's source code will be obtained and
+in which case its source code will be obtained and
 get sent for remote execution.  ``remote_exec`` returns
 a channel object whose symmetric counterpart channel
 is available to the remotely executing source.
 
 
 .. method:: Gateway.reconfigure([py2str_as_py3str=True, py3str_as_py2str=False])
 
-    reconfigures the string-coercion behaviour of the gateway
+    Reconfigures the string-coercion behaviour of the gateway
 
 .. _`Channel`:
 .. _`channel-api`:
@@ -164,17 +164,10 @@ you can execute this little test file::
     <RInfo 'numchannels=0, numexecuting=0, execmodel=thread'>
     1
 
-.. note::
-
-    With python3 you can (as of December 2013) only use the thread model
-    because neither eventlet-0.14.0 nor gevent-1.0 support Python3.
-    When they start to support Python3, execnet will probably just work
-    because it is itself Python3 compatible.
-
 How to execute in the main thread
 ------------------------------------------------
 
-When the remote side of a gateway uses the 'thread' model, execution
+When the remote side of a gateway uses the "thread" model, execution
 will preferably run in the main thread.  This allows GUI loops
 or other code to behave correctly.  If you, however, start multiple
 executions concurrently, they will run in non-main threads.
@@ -227,7 +220,7 @@ configure a tracing mechanism:
 .. _`dumps/loads`:
 .. _`dumps/loads API`:
 
-cross-interpreter serialization of python objects
+Cross-interpreter serialization of Python objects
 =======================================================
 
 .. versionadded:: 1.1

doc/conf.py

@@ -26,7 +26,11 @@
 # Add any Sphinx extension module names here, as strings.
 # They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -83,6 +87,16 @@
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+nitpicky = True
+nitpick_ignore = [
+    ("py:class", "execnet.gateway_base.ChannelFileRead"),
+    ("py:class", "execnet.gateway_base.ChannelFileWrite"),
+    ("py:class", "execnet.gateway.Gateway"),
+]
 
 # -- Options for HTML output --------------------------------------------------
 

doc/example/test_debug.rst

@@ -1,5 +1,5 @@
 
-Debugging execnet / Wire messages
+Debugging execnet / wire messages
 ===============================================================
 
 By setting the environment variable ``EXECNET_DEBUG`` you can

doc/example/test_group.rst

@@ -5,7 +5,7 @@ Usings Groups for managing multiple gateways
 ------------------------------------------------------
 
 Use ``execnet.Group`` to manage membership and lifetime of
-of multiple gateways::
+multiple gateways::
 
     >>> import execnet
     >>> group = execnet.Group(['popen'] * 2)
@@ -25,7 +25,7 @@ of multiple gateways::
     >>> group
     <Group []>
 
-Assigning Gateway IDs
+Assigning gateway IDs
 ------------------------------------------------------
 
 All gateways are created as part of a group and receive
@@ -66,12 +66,12 @@ you actually use the ``execnet.default_group``::
     >>> execnet.default_group.defaultspec # used for empty makegateway() calls
     'popen'
 
-Robust Termination of ssh/popen processes
+Robust termination of SSH/popen processes
 -----------------------------------------------
 
 Use ``group.terminate(timeout)`` if you want to terminate
-member gateways and ensure that no local sub processes remain
-you can specify a ``timeout`` after which an attempt at killing
+member gateways and ensure that no local subprocesses remain.
+You can specify a ``timeout`` after which an attempt at killing
 the related process is made::
 
     >>> import execnet
@@ -86,7 +86,7 @@ the related process is made::
 
 execnet aims to provide totally robust termination so if
 you have left-over processes or other termination issues
-please :doc:`report them <../support>`.  thanks!
+please :doc:`report them <../support>`.  Thanks!
 
 
 Using Groups to manage a certain type of gateway

doc/example/test_info.rst

@@ -1,5 +1,5 @@
-basic local and remote communication
-=========================================
+Basic local and remote communication
+====================================
 
 Execute source code in subprocess, communicate through a channel
 -------------------------------------------------------------------
@@ -25,8 +25,8 @@ messages between two processes.
 
 .. _`share-nothing model`: http://en.wikipedia.org/wiki/Shared_nothing_architecture
 
-remote-exec a function (avoiding inlined source part I)
--------------------------------------------------------------------
+Remote-exec a function (avoiding inlined source part I)
+-------------------------------------------------------
 
 You can send and remote execute parametrized pure functions like this:
 
@@ -49,8 +49,8 @@ Notes:
   between the nodes).
 
 
-remote-exec a module (avoiding inlined source part II)
---------------------------------------------------------------
+Remote-exec a module (avoiding inlined source part II)
+------------------------------------------------------
 
 You can pass a module object to ``remote_exec`` in which case
 its source code will be sent.  No dependencies will be transferred
@@ -86,8 +86,8 @@ A local subprocess gateway has the same working directory as the instantiatior::
 
 "ssh" gateways default to the login home directory.
 
-Get information from remote ssh account
---------------------------------------------
+Get information from remote SSH account
+---------------------------------------
 
 Use simple execution to obtain information from remote environments::
 
@@ -143,7 +143,7 @@ and use it to transfer information::
 
 
 
-a simple command loop pattern
+A simple command loop pattern
 --------------------------------------------------------------
 
 If you want the remote side to serve a number
@@ -189,6 +189,6 @@ itself into the remote socket endpoint::
     gw = execnet.makegateway("socket=TARGET-IP:8888")
 
 That's it, you can now use the gateway object just like
-a popen- or ssh-based one.
+a popen- or SSH-based one.
 
 .. include:: test_ssh_fileserver.rst

doc/example/test_multi.rst

@@ -1,4 +1,4 @@
-advanced (multi) channel communication
+Advanced (multi) channel communication
 =====================================================
 
 MultiChannel: container for multiple channels
@@ -19,7 +19,7 @@ Use ``execnet.MultiChannel`` to work with multiple channels::
     >>> sum(mch.receive_each())
     3
 
-receive results from sub processes with a Queue
+Receive results from sub processes with a Queue
 -----------------------------------------------------
 
 Use ``MultiChannel.make_receive_queue()`` to get a queue
@@ -52,7 +52,7 @@ data immediately and without blocking execution::
 Note that the callback function will be executed in the
 receiver thread and should not block or run for too long.
 
-robustly receive results and termination notification
+Robustly receive results and termination notification
 -----------------------------------------------------
 
 Use ``MultiChannel.make_receive_queue(endmarker)`` to specify
@@ -76,7 +76,7 @@ is blocked in execution and is terminated/killed::
 
 
 
-saturate multiple Hosts and CPUs with tasks to process
+Saturate multiple Hosts and CPUs with tasks to process
 --------------------------------------------------------
 
 If you have multiple CPUs or hosts you can create as many

doc/example/test_proxy.rst

@@ -1,10 +1,10 @@
-Managing Proxied gateways
+Managing proxied gateways
 ==========================
 
-Simple Proxying
+Simple proxying
 ----------------
 
-Using the via arg of specs we can create a gateway
+Using the ``via`` arg of specs we can create a gateway
 whose io is created on a remote gateway and proxied to the master.
 
 The simplest use case, is where one creates one master process

doc/example/test_ssh_fileserver.rst

@@ -1,4 +1,3 @@
-
 Receive file contents from remote SSH account
 -----------------------------------------------------