Merge pull request #386 from moreati/doc-cleanups

Documentation cleanups

docs/ansible.rst

@@ -290,8 +290,7 @@ command line, or as host and group variables.
 File Transfer
 ~~~~~~~~~~~~~
 
-Normally `sftp(1) <https://linux.die.net/man/1/sftp>`_ or
-`scp(1) <https://linux.die.net/man/1/scp>`_ are used to copy files by the
+Normally `sftp(1)`_ or `scp(1)`_ are used to copy files by the
 `assemble <http://docs.ansible.com/ansible/latest/modules/assemble_module.html>`_,
 `copy <http://docs.ansible.com/ansible/latest/modules/copy_module.html>`_,
 `patch <http://docs.ansible.com/ansible/latest/modules/patch_module.html>`_,
@@ -302,6 +301,9 @@ actions, or when uploading modules with pipelining disabled. With Mitogen
 copies are implemented natively using the same interpreters, connection tree,
 and routed message bus that carries RPCs.
 
+.. _scp(1): https://linux.die.net/man/1/scp
+.. _sftp(1): https://linux.die.net/man/1/sftp
+
 This permits direct streaming between endpoints regardless of execution
 environment, without necessitating temporary copies in intermediary accounts or
 machines, for example when ``become`` is active, or in the presence of
@@ -321,8 +323,7 @@ to rename over any existing file. This ensures the file remains consistent at
 all times, in the event of a crash, or when overlapping `ansible-playbook` runs
 deploy differing file contents.
 
-The `sftp(1) <https://linux.die.net/man/1/sftp>`_ and `scp(1)
-<https://linux.die.net/man/1/sftp>`_ tools may cause undetected data corruption
+The `sftp(1)`_ and `scp(1)`_ tools may cause undetected data corruption
 in the form of truncated files, or files containing intermingled data segments
 from overlapping runs. As part of normal operation, both tools expose a window
 where readers may observe inconsistent file contents.
@@ -445,8 +446,7 @@ Ansible may:
 * Create a directory owned by the SSH user either under ``remote_tmp``, or a
   system-default directory,
 * Upload action dependencies such as non-new style modules or rendered
-  templates to that directory via `sftp(1) <https://linux.die.net/man/1/sftp>`_
-  or `scp(1) <https://linux.die.net/man/1/scp>`_.
+  templates to that directory via `sftp(1)`_ or `scp(1)`_.
 * Attempt to modify the directory's access control list to grant access to the
   target user using `setfacl(1) <https://linux.die.net/man/1/setfacl>`_,
   requiring that tool to be installed and a supported filesystem to be in use,

docs/api.rst

@@ -458,7 +458,7 @@ Router Class
             rich data structures that cannot normally be passed via a
             serialization.
 
-        :param Context via:
+        :param mitogen.core.Context via:
             Same as the `via` parameter for :meth:`local`.
 
         :param bool debug:
@@ -1095,7 +1095,8 @@ Select Class
         each, returning the result of calling `msg.unpickle()` on each in turn.
         Results are returned in the order they arrived.
 
-        This is sugar for handling batch :class:`Context.call_async`
+        This is sugar for handling batch
+        :meth:`Context.call_async <mitogen.parent.Context.call_async>`
         invocations:
 
         .. code-block:: python
@@ -1262,7 +1263,8 @@ Broker Class
     .. method:: keep_alive
 
         Return :data:`True` if any reader's :attr:`Side.keep_alive`
-        attribute is :data:`True`, or any :class:`Context` is still
+        attribute is :data:`True`, or any
+        :class:`Context <mitogen.core.Context>` is still
         registered that is not the master. Used to delay shutdown while some
         important work is in progress (e.g. log draining).
 

docs/getting_started.rst

@@ -208,7 +208,7 @@ started the context, however as shown, this can be overridden.
 Calling A Function
 ------------------
 
-.. currentmodule:: mitogen.master
+.. currentmodule:: mitogen.parent
 
 Now that some contexts exist, it is time to execute code in them. Any regular
 function, static method, or class method reachable directly from module scope

docs/toc.rst

@@ -15,3 +15,8 @@ Table Of Contents
    examples
    internals
    shame
+
+.. toctree::
+   :hidden:
+
+   services