Merge pull request #211 from goodboy/new_docs_polish

New docs theme, readme actors rant.

docs/README.rst

@@ -3,18 +3,15 @@
 |gh_actions|
 |docs|
 
-.. _actor model: https://en.wikipedia.org/wiki/Actor_model
-.. _trio: https://github.com/python-trio/trio
-.. _multi-processing: 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 a `structured concurrent`_, multi-processing_ runtime built on trio_.
 
-``tractor`` is a `structured concurrent`_ "`actor model`_" built on trio_ and multi-processing_.
+Fundamentally ``tractor`` gives you parallelism via ``trio``-"*actors*":
+our nurseries_ let you spawn new Python processes which each run a ``trio``
+scheduled runtime - a call to ``trio.run()``.
 
-We pair structured concurrency and true multi-core parallelism with
-the aim of being the multi-processing framework *you always wanted*.
+We believe the system adhere's to the `3 axioms`_ of an "`actor model`_"
+but likely *does not* look like what *you* probably think an "actor
+model" looks like, and that's *intentional*.
 
 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`_.
@@ -23,12 +20,13 @@ A great place to start is the `trio docs`_ and this `blog post`_.
 Features
 --------
 - **It's just** a ``trio`` API
-- Infinitely nesteable process trees
-- Built-in APIs for inter-process streaming
-- A (first ever?) "native" multi-core debugger for Python using `pdb++`_
-- Support for multiple process spawning backends
-- A modular transport layer, allowing for custom serialization,
+- *Infinitely nesteable* process trees
+- Built-in inter-process streaming APIs
+- A (first ever?) "native" multi-core debugger UX for Python using `pdb++`_
+- Support for a swappable, OS specific, process spawning layer
+- A modular transport stack, allowing for custom serialization,
   communications protocols, and environment specific IPC primitives
+- `structured concurrency`_ from the ground up
 
 
 Run a func in a process
@@ -244,19 +242,57 @@ distributed Python. You can think of it as a ``trio``
 stdlib's ``multiprocessing`` but built on async programming primitives
 from the ground up.
 
-``tractor``'s nurseries let you spawn ``trio`` *"actors"*: new Python
-processes which each run a ``trio`` scheduled runtime - a call to ``trio.run()``.
-
 Don't be scared off by this description. ``tractor`` **is just** ``trio``
 but with nurseries for process management and cancel-able streaming IPC.
 If you understand how to work with ``trio``, ``tractor`` will give you
-the parallelism you've been missing.
+the parallelism you may have been needing.
+
+
+Wait, huh?! I thought "actors" have messages, and mailboxes and stuff?!
+***********************************************************************
+Let's stop and ask how many canon actor model papers have you actually read ;)
+
+From our experience many "actor systems" aren't really "actor models"
+since they **don't adhere** to the `3 axioms`_ and pay even less
+attention to the problem of *unbounded non-determinism* (which was the
+whole point for creation of the model in the first place).
+
+From the author's mouth, **the only thing required** is `adherance to`_
+the `3 axioms`_, *and that's it*.
+
+``tractor`` adheres to said base requirements of an "actor model"::
+
+    In response to a message, an actor may:
 
-"Actors" communicate by exchanging asynchronous messages_ and avoid
-sharing state. The intention of this model is to allow for highly
-distributed software that, through the adherence to *structured
-concurrency*, results in systems which fail in predictable and
-recoverable ways.
+    - send a finite number of new messages
+    - create a finite number of new actors
+    - designate a new behavior to process subsequent messages
+
+
+**and** requires *no further api changes* to accomplish this.
+
+If you want do debate this further please feel free to chime in on our
+chat or discuss on one of the following issues *after you've read
+everything in them*::
+
+- https://github.com/goodboy/tractor/issues/210
+- https://github.com/goodboy/tractor/issues/18
+
+
+Let's clarify our parlance
+**************************
+Whether or not ``tractor`` has "actors" underneath should be mostly
+irrelevant to users other then for referring to the interactions of our
+primary runtime primitives: each Python process + ``trio.run()``
++ surrounding IPC machinery. These are our high level, base
+*runtime-units-of-abstraction* which both *are* (as much as they can
+be in Python) and will be referred to as our *"actors"*.
+
+The main goal of ``tractor`` is is to allow for highly distributed
+software that, through the adherence to *structured concurrency*,
+results in systems which fail in predictable, recoverable and maybe even
+understandable ways; being an "actor model" is just one way to describe
+properties of the system.
 
 
 What's on the TODO:
@@ -278,6 +314,15 @@ say hi, please feel free to reach us in our `matrix channel`_.  If
 matrix seems too hip, we're also mostly all in the the `trio gitter
 channel`_!
 
+.. _nurseries: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/#nurseries-a-structured-replacement-for-go-statements
+.. _actor model: https://en.wikipedia.org/wiki/Actor_model
+.. _trio: https://github.com/python-trio/trio
+.. _multi-processing: 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
+.. _3 axioms: https://www.youtube.com/watch?v=7erJ1DV_Tlo&t=162s
+.. _adherance to: https://www.youtube.com/watch?v=7erJ1DV_Tlo&t=1821s
 .. _trio gitter channel: https://gitter.im/python-trio/general
 .. _matrix channel: https://matrix.to/#/!tractor:matrix.org
 .. _pdb++: https://github.com/pdbpp/pdbpp
@@ -286,7 +331,6 @@ channel`_!
 .. _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/
 .. _trio-parallel: https://github.com/richardsheridan/trio-parallel

docs/conf.py

@@ -54,28 +54,44 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_typlog_theme'
+html_theme = 'sphinx_book_theme'
 
-pygments_style = 'sphinx'
+pygments_style = 'algol_nu'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    'logo': 'tractor_logo_side.svg',
-    'description': 'Structured concurrent "actors"',
-    'github_user': 'goodboy',
-    'github_repo': 'tractor',
+    # 'logo': 'tractor_logo_side.svg',
+    # 'description': 'Structured concurrent "actors"',
+    "repository_url": "https://github.com/goodboy/tractor",
+    "use_repository_button": True,
+    "home_page_in_toc": False,
+    "show_toc_level": 1,
+    "path_to_docs": "docs",
+
 }
 html_sidebars = {
     "**": [
-        'logo.html',
-        'github.html',
-        'relations.html',
-        'searchbox.html'
-    ]
+        "sbt-sidebar-nav.html",
+        "sidebar-search-bs.html",
+        # 'localtoc.html',
+    ],
+    #     'logo.html',
+    #     'github.html',
+    #     'relations.html',
+    #     'searchbox.html'
+    # ]
 }
 
+# doesn't seem to work?
+# extra_navbar = "<p>nextttt-gennnnn</p>"
+
+html_title = ''
+html_logo = '_static/tractor_logo_side.svg'
+html_favicon = '_static/tractor_logo_side.svg'
+# show_navbar_depth = 1
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/index.rst

@@ -3,12 +3,13 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-tractor
-=======
+``tractor``
+===========
+
 A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
 .. _actor model: https://en.wikipedia.org/wiki/Actor_model
@@ -58,8 +59,6 @@ say hi, please feel free to ping me on the `trio gitter channel`_!
 .. _trio gitter channel: https://gitter.im/python-trio/general
 
 
-.. contents::
-
 
 Philosophy
 ----------

requirements-docs.txt

@@ -1,2 +1,2 @@
 sphinx
-sphinx_typlog_theme
+sphinx_book_theme