Docs restructure (#869)

ansible · Oct 9, 2023 · 215c103 · 215c103
1 parent 6740b44
commit 215c103
Show file tree

Hide file tree

Showing 16 changed files with 245 additions and 153 deletions.
diff --git a/docs/source/release_process.rst → docs/source/contributing.rst b/docs/source/release_process.rst → docs/source/contributing.rst
@@ -1,3 +1,24 @@
+.. _contributing:
+
+******************
+Contributor guide
+******************
+
+Receptor is an open source project that lives at https://github.com/ansible/receptor
+
+.. contents::
+   :local:
+
+Code of conduct
+================
+
+All project contributors must abide by the `Ansible Code of Conduct <https://docs.ansible.com/ansible/latest/community/code_of_conduct.html>`_.
+
+Contributing
+=============
+
+Receptor welcomes community contributions!  See the :ref:`dev_guide` for details.
+
 Release process
 ===============
 

diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst
@@ -1,10 +1,18 @@
+.. _dev_guide:
+
 Developer guide
 ================
 
 Receptor is an open source project that lives at https://github.com/ansible/receptor
 
+.. contents::
+   :local:
+
+See the :ref:`contributing` for more general details.
+
+
 Testing
-^^^^^^^
+--------
 
 Pull requests must pass a suite of integration tests before being merged into ``devel``.
 
@@ -39,12 +47,12 @@ For example, to create/update mocks for Workceptor, we can run:
     mockgen -source=pkg/workceptor/workceptor.go -destination=pkg/workceptor/mock_workceptor/workceptor.go
 
 Source code
-^^^^^^^^^^^
+-----------
 
 The next couple of sections are aimed to orient developers to the receptor codebase and provide a starting point for understanding how receptor works.
 
 Parsing receptor.conf
-"""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^
 
 Let's see how items in the config file are mapped to Golang internals.
 
@@ -126,7 +134,7 @@ This gets a new TCP dialer object and passes it to the netceptor AddBackend meth
 In general, when studying how the start up process works in receptor, take a look at the Init, Prepare, and Run methods throughout the code, as these are the entry points to running those specific components of receptor.
 
 Ping
-""""
+^^^^
 
 Studying how pings work in receptor will provide a useful glimpse into the internal workings of netceptor -- the main component of receptor that handles connections and data traffic over the mesh.
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,129 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Introduction
-============
+###############################
+Ansible Receptor documentation
+###############################
 
 Receptor is an overlay network intended to ease the distribution of work across a large and dispersed collection of workers. Receptor nodes establish peer-to-peer connections with each other via existing networks. Once connected, the receptor mesh provides datagram (UDP-like) and stream (TCP-like) capabilities to applications, as well as robust unit-of-work handling with resiliency against transient network failures.
 
-Terminology and Concepts
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-- `receptor`: The receptor application taken as a whole, which typically runs as a daemon.
-- `receptorctl`: A user-facing command line used to interact with receptor, typically over a Unix domain socket.
-- `node`: A single running instance of receptor.
-- `node ID`: An arbitrary string identifying a single node, analogous to an IP address.
-- `backend`: A type of connection that receptor nodes can pass traffic over. Current backends include TCP, UDP and websockets.
-- `control service`: A built-in service that usually runs under the name `control`.  Used to report status and to launch and monitor work.
-- `netceptor`: The component of receptor that handles all networking functionality.
-- `workceptor`: The component of receptor that handles work units.
-
-Installation
-^^^^^^^^^^^^
-
-Download and extract precompiled binary for your OS and platform from `the releases page on GitHub <https://github.com/ansible/receptor/releases>`_
-
-Alternatively, you can compile from source code (Golang 1.19+ required)
-
-.. code::
-
-    make receptor
-
-Test the installation with
-
-.. code::
-
-    receptor --help
-    receptor --version
-
-The preferred way to interact with receptor nodes is to use the receptorctl command line tool
-
-.. code::
-
-    pip install receptorctl
-
-receptorctl will be used in various places throughout this documentation.
-
-Basic usage
-^^^^^^^^^^^
-
-Run the following command in a terminal to start a node called `foo`,
-
-.. code::
-
-    receptor --node id=foo --local-only --log-level Debug
-
-The log shows the receptor node started successfully
-
-``INFO 2021/07/22 22:40:36 Initialization complete``
-
-Supported log levels, in increasing verbosity, are Error, Warning, Info and Debug.
-
-Note: stop the receptor process with ``ctrl-c``
-
-Config file
-^^^^^^^^^^^
-
-Receptor can be configured on the command-line, exemplified above, or via a yaml config file. All actions and parameters shown in ``receptor --help`` can be written to a config file.
-
-.. code-block:: yaml
-
-    ---
-    - node:
-        id: foo
-
-    - local-only
-
-    - log-level:
-        level: Debug
-
-Start receptor using the config file
-
-.. code::
-
-    receptor --config foo.yml
-
-Changing the configuration file does take effect until the receptor process is restarted.
-
-Container image
-^^^^^^^^^^^^^^^
-
-.. code::
-
-    podman pull quay.io/ansible/receptor
-
-Start a container, which automatically runs receptor with the default config located at ``/etc/receptor/receptor.conf``
-
-.. code::
-
-    podman run -it --rm --name receptor quay.io/ansible/receptor
-
-In another terminal, issue a basic "status" command to the running receptor process
-
-.. code::
-
-    $ podman exec receptor receptorctl status
-    Node ID: d9b5a8e3c156
-    Version: 1.0.0
-    System CPU Count: 8
-    System Memory MiB: 15865
-
-    Node         Service   Type       Last Seen           Tags            Work Types
-    d9b5a8e3c156 control   Stream     2021-08-04 19:26:14 -               -
-
-Note: the config file does not specify a node ID, so the hostname (on the container) is chosen as the node ID.
-
 .. toctree::
-   :maxdepth: 3
-   :caption: Contents:
+   :maxdepth: 2
 
-   self
-   connecting_nodes
-   interacting_with_nodes
-   workceptor
-   k8s
-   tls
-   firewall
-   edge_networks
+   installation
+   user_guide/index
    developer_guide
-   release_process
+   contributing
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -0,0 +1,28 @@
+.. _installing:
+
+*******************
+Installation guide
+*******************
+
+Download and extract precompiled binary for your OS and platform from `the releases page on GitHub <https://github.com/ansible/receptor/releases>`_
+
+Alternatively, you can compile from source code (Golang 1.19+ required)
+
+.. code::
+
+    make receptor
+
+Test the installation with
+
+.. code::
+
+    receptor --help
+    receptor --version
+
+The preferred way to interact with receptor nodes is to use the receptorctl command line tool
+
+.. code::
+
+    pip install receptorctl
+
+receptorctl will be used in various places throughout this documentation.
diff --git a/docs/source/user_guide/basic_usage.rst b/docs/source/user_guide/basic_usage.rst
@@ -0,0 +1,74 @@
+Using Receptor
+===============
+
+. contents::
+   :local:
+
+Configuring Receptor with the CLI
+-----------------------------------
+
+Run the following command in a terminal to start a node called `foo`,
+
+.. code::
+
+    receptor --node id=foo --local-only --log-level Debug
+
+The log shows the receptor node started successfully
+
+``INFO 2021/07/22 22:40:36 Initialization complete``
+
+Supported log levels, in increasing verbosity, are Error, Warning, Info and Debug.
+
+Note: stop the receptor process with ``ctrl-c``
+
+Configuring Receptor with a config file
+----------------------------------------
+
+Receptor can be configured on the command-line, exemplified above, or via a yaml config file. All actions and parameters shown in ``receptor --help`` can be written to a config file.
+
+.. code-block:: yaml
+
+    ---
+    - node:
+        id: foo
+
+    - local-only
+
+    - log-level:
+        level: Debug
+
+Start receptor using the config file
+
+.. code::
+
+    receptor --config foo.yml
+
+Changing the configuration file does take effect until the receptor process is restarted.
+
+Use Receptor through a container image
+---------------------------------------
+
+.. code::
+
+    podman pull quay.io/ansible/receptor
+
+Start a container, which automatically runs receptor with the default config located at ``/etc/receptor/receptor.conf``
+
+.. code::
+
+    podman run -it --rm --name receptor quay.io/ansible/receptor
+
+In another terminal, issue a basic "status" command to the running receptor process
+
+.. code::
+
+    $ podman exec receptor receptorctl status
+    Node ID: d9b5a8e3c156
+    Version: 1.0.0
+    System CPU Count: 8
+    System Memory MiB: 15865
+
+    Node         Service   Type       Last Seen           Tags            Work Types
+    d9b5a8e3c156 control   Stream     2021-08-04 19:26:14 -               -
+
+Note: the config file does not specify a node ID, so the hostname (on the container) is chosen as the node ID.
diff --git a/docs/source/connecting_nodes.rst → docs/source/user_guide/connecting_nodes.rst b/docs/source/connecting_nodes.rst → docs/source/user_guide/connecting_nodes.rst
@@ -1,9 +1,14 @@
 Connecting nodes
 ================
 
+.. contents::
+   :local:
+
+
 Connect nodes via receptor backends. TCP, UDP, and websockets are currently supported. For example, ``tcp-peer`` can be used to connect to another node's ``tcp-listener``, and ``ws-peer`` can be used to connect to another node's ``ws-listener``.
 
 .. image:: mesh.png
+   :alt: Connected nodes as netceptor peers
 
 foo.yml
 
@@ -80,7 +85,7 @@ Logs from `fish` shows a successful connection to `bar` via `foo`.
 
 
 Configuring backends
-^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 ``redial`` If set to true, receptor will automatically attempt to redial and restore connections that are lost.
 

diff --git a/docs/source/edge.png → docs/source/user_guide/edge.png b/docs/source/edge.png → docs/source/user_guide/edge.png
diff --git a/docs/source/edge_networks.rst → docs/source/user_guide/edge_networks.rst b/docs/source/edge_networks.rst → docs/source/user_guide/edge_networks.rst
@@ -3,12 +3,16 @@ Support for Edge Networks
 
 Recptor out-of-the-box has the ability to support complicated networking environments including edge networks.
 
+.. contents::
+   :local:
+
 Consider the following environment:
 
 .. image:: edge.png
+   :alt: Network diagram with netceptor peers to edge network
 
 Configurable-Items
-^^^^^^^^^^^^^^^^^^
+-------------------
 
 Receptor encapsulates the concepts of `below-the-mesh` and `above-the-mesh` connections. Please refer to :doc:`tls` for a better understanding of these networking layers.
 

diff --git a/docs/source/firewall.rst → docs/source/user_guide/firewall.rst b/docs/source/firewall.rst → docs/source/user_guide/firewall.rst