diff --git a/docs/ansible.rst b/docs/ansible.rst index 529dd4a6..517446f8 100644 --- a/docs/ansible.rst +++ b/docs/ansible.rst @@ -290,8 +290,7 @@ command line, or as host and group variables. File Transfer ~~~~~~~~~~~~~ -Normally `sftp(1) `_ or -`scp(1) `_ are used to copy files by the +Normally `sftp(1)`_ or `scp(1)`_ are used to copy files by the `assemble `_, `copy `_, `patch `_, @@ -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) `_ and `scp(1) -`_ 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) `_ - or `scp(1) `_. + 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) `_, requiring that tool to be installed and a supported filesystem to be in use, diff --git a/docs/api.rst b/docs/api.rst index 6a9da1d8..72a6b4db 100644 --- a/docs/api.rst +++ b/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 ` 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 ` is still registered that is not the master. Used to delay shutdown while some important work is in progress (e.g. log draining). diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 436b34a1..1c92a559 100644 --- a/docs/getting_started.rst +++ b/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 diff --git a/docs/toc.rst b/docs/toc.rst index 357fea3f..7b3274a9 100644 --- a/docs/toc.rst +++ b/docs/toc.rst @@ -15,3 +15,8 @@ Table Of Contents examples internals shame + +.. toctree:: + :hidden: + + services