Mirror readme off docs intro

README.rst

@@ -1,17 +1,24 @@
 tractor
 =======
-An async-native "`actor model`_" built on trio_ and multiprocessing_.
+A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_.
 
+|travis| |docs|
 
-|travis|
+.. toctree::
-
+   :maxdepth: 2
-.. |travis| image:: https://img.shields.io/travis/goodboy/tractor/master.svg
+   :caption: Contents:
-    :target: https://travis-ci.org/goodboy/tractor
 
+.. _actor model: https://en.wikipedia.org/wiki/Actor_model
+.. _trio: https://github.com/python-trio/trio
+.. _multiprocessing: https://en.wikipedia.org/wiki/Multiprocessing
+.. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles
+.. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich
+.. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228
 
 
 ``tractor`` is an attempt to bring trionic_ `structured concurrency`_ to
-distributed multi-core Python.
+distributed multi-core Python; it aims to be the Python multi-processing
+framework *you always wanted*.
 
 ``tractor`` lets you spawn ``trio`` *"actors"*: processes which each run
 a ``trio`` scheduled task tree (also known as an `async sandwich`_).
@@ -23,44 +30,13 @@ many hosts.
 The first step to grok ``tractor`` is to get the basics of ``trio`` down.
 A great place to start is the `trio docs`_ and this `blog post`_.
 
-.. _actor model: https://en.wikipedia.org/wiki/Actor_model
-.. _trio: https://github.com/python-trio/trio
-.. _multiprocessing: https://en.wikipedia.org/wiki/Multiprocessing
-.. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles
-.. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich
-.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate
-.. _causality: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#c-c-c-c-causality-breaker
-.. _shared nothing architecture: https://en.wikipedia.org/wiki/Shared-nothing_architecture
-.. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts
-.. _channels: https://en.wikipedia.org/wiki/Channel_(programming)
-.. _chaos engineering: http://principlesofchaos.org/
 .. _messages: https://en.wikipedia.org/wiki/Message_passing
 .. _trio docs: https://trio.readthedocs.io/en/latest/
 .. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
 .. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
-
+.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts
-
+.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony
-Philosophy
+.. _async generators: https://www.python.org/dev/peps/pep-0525/
-----------
-``tractor`` aims to be the Python multi-processing framework *you always wanted*.
-
-Its tenets non-comprehensively include:
-
-- strict adherence to the `concept-in-progress`_ of *structured concurrency*
-- no spawning of processes *willy-nilly*; causality_ is paramount!
-- (remote) errors `always propagate`_ back to the parent supervisor
-- verbatim support for ``trio``'s cancellation_ system
-- `shared nothing architecture`_
-- no use of *proxy* objects or shared references between processes
-- an immersive debugging experience
-- anti-fragility through `chaos engineering`_
-
-
-.. warning:: ``tractor`` is in alpha-alpha and is expected to change rapidly!
-    Expect nothing to be set in stone. Your ideas about where it should go
-    are greatly appreciated!
-
-.. _concept-in-progress: https://trio.discourse.group/t/structured-concurrency-kickoff/55
 
 
 Install
@@ -80,3 +56,12 @@ community). If you want to help, have suggestions or just want to
 say hi, please feel free to ping me on the `trio gitter channel`_!
 
 .. _trio gitter channel: https://gitter.im/python-trio/general
+A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_.
+
+
+.. |travis| image:: https://img.shields.io/travis/goodboy/tractor/master.svg
+    :target: https://travis-ci.org/goodboy/tractor
+
+.. |docs| image:: https://readthedocs.org/projects/tractor/badge/?version=latest
+    :target: https://tractor.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status

docs/index.rst

@@ -16,12 +16,6 @@ A `structured concurrent`_, async-native "`actor model`_" built on trio_ and mul
 .. _multiprocessing: https://en.wikipedia.org/wiki/Multiprocessing
 .. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles
 .. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich
-.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate
-.. _causality: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#c-c-c-c-causality-breaker
-.. _shared nothing architecture: https://en.wikipedia.org/wiki/Shared-nothing_architecture
-.. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts
-.. _channels: https://en.wikipedia.org/wiki/Channel_(programming)
-.. _chaos engineering: http://principlesofchaos.org/
 .. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228
 
 
@@ -43,9 +37,6 @@ A great place to start is the `trio docs`_ and this `blog post`_.
 .. _trio docs: https://trio.readthedocs.io/en/latest/
 .. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
 .. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/
-.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts
-.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony
-.. _async generators: https://www.python.org/dev/peps/pep-0525/
 
 
 Install
@@ -104,6 +95,15 @@ reactive style for IPC.
     are greatly appreciated!
 
 .. _concept-in-progress: https://trio.discourse.group/t/structured-concurrency-kickoff/55
+.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts
+.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony
+.. _async generators: https://www.python.org/dev/peps/pep-0525/
+.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate
+.. _causality: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#c-c-c-c-causality-breaker
+.. _shared nothing architecture: https://en.wikipedia.org/wiki/Shared-nothing_architecture
+.. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts
+.. _channels: https://en.wikipedia.org/wiki/Channel_(programming)
+.. _chaos engineering: http://principlesofchaos.org/
 
 
 Examples