Fix Sphinx issues with documentation (#953)

docs/source/contributing.rst

@@ -1,5 +1,3 @@
-.. _contributing:
-
 ******************
 Contributor guide
 ******************
@@ -22,7 +20,7 @@ Receptor welcomes community contributions!  See the :ref:`dev_guide` for details
 Release process
 ===============
 
-Maintainers have the ability to run the `Stage Release <https://github.com/ansible/receptor/actions/workflows/stage.yml>`_ workflow. Running this workflow will:
+Maintainers have the ability to run the `Stage Release`_ workflow. Running this workflow will:
 
 - Build and push the container image to ghcr.io. This serves as a staging environment where the image can be tested.
 - Create a draft release at `<https://github.com/ansible/receptor/releases>`_
@@ -36,4 +34,7 @@ After the release is published, the `Promote Release <https://github.com/ansible
 - Build binaries for various OSes/platforms, and attach them to the `release <https://github.com/ansible/receptor/releases>`_.
 
 .. note::
-  If you need to re-run `Stage Release <https://github.com/ansible/receptor/actions/workflows/stage.yml>`_ more than once you must delete the tag beforehand, otherwise the workflow will fail.
+  If you need to re-run `Stage Release`_ more than once you must delete the tag beforehand, otherwise the workflow will fail.
+
+.. _Stage Release: https://github.com/ansible/receptor/actions/workflows/stage.yml
+

docs/source/developer_guide.rst

@@ -8,7 +8,7 @@ Receptor is an open source project that lives at https://github.com/ansible/rece
 .. contents::
    :local:
 
-See the :ref:`contributing` for more general details.
+See the :ref:`contributing:contributing` for more general details.
 
 
 Testing
@@ -91,11 +91,11 @@ Here is the Prepare method for ``TCPDialerCfg``. By the time this code executes,
 
     // Prepare verifies the parameters are correct.
     func (cfg TCPDialerCfg) Prepare() error {
-    	if cfg.Cost <= 0.0 {
-    		return fmt.Errorf("connection cost must be positive")
-    	}
+        if cfg.Cost <= 0.0 {
+            return fmt.Errorf("connection cost must be positive")
+        }
 
-    	return nil
+        return nil
     }
 
 This simply does a check to make sure the provided Cost is valid.
@@ -106,27 +106,27 @@ The Run method for the ``TCPDialerCfg`` object:
 
     // Run runs the action.
     func (cfg TCPDialerCfg) Run() error {
-    	logger.Debug("Running TCP peer connection %s\n", cfg.Address)
-    	host, _, err := net.SplitHostPort(cfg.Address)
-    	if err != nil {
-    		return err
-    	}
-    	tlscfg, err := netceptor.MainInstance.GetClientTLSConfig(cfg.TLS, host, "dns")
-    	if err != nil {
-    		return err
-    	}
-    	b, err := NewTCPDialer(cfg.Address, cfg.Redial, tlscfg)
-    	if err != nil {
-    		logger.Error("Error creating peer %s: %s\n", cfg.Address, err)
-
-    		return err
-    	}
-    	err = netceptor.MainInstance.AddBackend(b, cfg.Cost, nil)
-    	if err != nil {
-    		return err
-    	}
-
-    	return nil
+        logger.Debug("Running TCP peer connection %s\n", cfg.Address)
+        host, _, err := net.SplitHostPort(cfg.Address)
+        if err != nil {
+            return err
+        }
+        tlscfg, err := netceptor.MainInstance.GetClientTLSConfig(cfg.TLS, host, "dns")
+        if err != nil {
+            return err
+        }
+        b, err := NewTCPDialer(cfg.Address, cfg.Redial, tlscfg)
+        if err != nil {
+            logger.Error("Error creating peer %s: %s\n", cfg.Address, err)
+
+            return err
+        }
+        err = netceptor.MainInstance.AddBackend(b, cfg.Cost, nil)
+        if err != nil {
+            return err
+        }
+
+        return nil
     }
 
 This gets a new TCP dialer object and passes it to the netceptor AddBackend method, so that it can be processed further. AddBackend will start proper Go routines that periodically dial the address defined in the TCP dialer structure, which will lead to a proper TCP connection to another receptor node.
@@ -147,7 +147,7 @@ The control-service on `foo` will receive this command and subsequently call the
 .. code-block:: go
 
     func ping(nc *netceptor.Netceptor, target string, hopsToLive byte) (time.Duration, string, error) {
-    	pc, err := nc.ListenPacket("")
+        pc, err := nc.ListenPacket("")
 
 ``target`` is the target node, "bar" in this case.
 
@@ -158,13 +158,13 @@ The control-service on `foo` will receive this command and subsequently call the
 .. code-block:: go
 
     pc := &PacketConn{
-    	s:            s,
-    	localService: service,
-    	recvChan:     make(chan *messageData),
-    	advertise:    false,
-    	adTags:       nil,
-    	connType:     ConnTypeDatagram,
-    	hopsToLive:   s.maxForwardingHops,
+        s:            s,
+        localService: service,
+        recvChan:     make(chan *messageData),
+        advertise:    false,
+        adTags:       nil,
+        connType:     ConnTypeDatagram,
+        hopsToLive:   s.maxForwardingHops,
     }
 
     s.listenerRegistry[service] = pc
@@ -189,12 +189,12 @@ Sends an empty message to the address "bar:ping" on the mesh. Recall that nodes
 .. code-block:: go
 
     md := &messageData{
-    	FromNode:    s.nodeID,
-    	FromService: fromService,
-    	ToNode:      toNode,
-    	ToService:   toService,
-    	HopsToLive:  hopsToLive,
-    	Data:        data,
+        FromNode:    s.nodeID,
+        FromService: fromService,
+        ToNode:      toNode,
+        ToService:   toService,
+        HopsToLive:  hopsToLive,
+        Data:        data,
     }
 
     return s.handleMessageData(md)
@@ -239,8 +239,8 @@ So before the "ping" command was issued, this protoWriter Go routine was already
 .. code-block:: go
 
     func (ns *TCPSession) Send(data []byte) error {
-    	buf := ns.framer.SendData(data)
-    	n, err := ns.conn.Write(buf)
+        buf := ns.framer.SendData(data)
+        n, err := ns.conn.Write(buf)
 
 ``ns.conn`` is net.Conn object, which is part of the Golang standard library.
 
@@ -306,7 +306,7 @@ This checks whether the destination node indicated in the message is the current
 .. code-block:: go
 
     func (s *Netceptor) handlePing(md *messageData) error {
-    	return s.sendMessage("ping", md.FromNode, md.FromService, []byte{})
+        return s.sendMessage("ping", md.FromNode, md.FromService, []byte{})
     }
 
 This is the ping reply handler. It sends an empty message to the FromNode (`foo`).

docs/source/installation.rst

@@ -25,4 +25,4 @@ The preferred way to interact with receptor nodes is to use the receptorctl comm
 
     pip install receptorctl
 
-receptorctl will be used in various places throughout this documentation.
+receptorctl will be used in various places throughout this documentation.

docs/source/user_guide/basic_usage.rst

@@ -2,6 +2,7 @@ Using Receptor
 ===============
 
 . contents::
+
    :local:
 
 Configuring Receptor with the CLI

docs/source/user_guide/edge_networks.rst

@@ -70,4 +70,4 @@ fish.yml
     - tcp-peer:
         address: localhost:2222
 
-*Note* - All Receptor nodes in the mesh must define a `maxidleconnectiontimeout` value, if this value is consumed on ANY node. The effective `maxidleconnectiontimeout` value is the minumum value between all the nodes in the mesh.
+*Note* - All Receptor nodes in the mesh must define a `maxidleconnectiontimeout` value, if this value is consumed on ANY node. The effective `maxidleconnectiontimeout` value is the minumum value between all the nodes in the mesh.

docs/source/user_guide/index.rst

@@ -34,7 +34,7 @@ This guide describes how to use receptor in multiple environments and uses the f
 
    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.
 

docs/source/user_guide/interacting_with_nodes.rst

@@ -109,7 +109,7 @@ One can also connect to the locally running control service in a similar manner
 
 Once connected to a control service, one can issue commands like "status" or "work list" and get JSON-formatted responses back.
 
-Keep in mind that a "work submit" command will require a payload. Type out the payload contents and press ctrl-D to send the EOF signal. The socket will then close and work will begin. See :ref:`workceptor` for more on submitting work via receptor.
+Keep in mind that a "work submit" command will require a payload. Type out the payload contents and press ctrl-D to send the EOF signal. The socket will then close and work will begin. See :ref:`user_guide/workceptor:workceptor` for more on submitting work via receptor.
 
 .. _control_service_commands:
 
@@ -127,7 +127,7 @@ String example:
 JSON example:
 
 .. code-block:: json
-  
+
     {
       "command":"work",
       "subcommand":"submit",

docs/source/user_guide/k8s.rst

@@ -52,15 +52,15 @@ Note at this time it is necessary to have either a tcp-listener or a tcp-peer to
 
 Note: at least one of the containers in the pod spec must be named "worker". This is the container that stdin is passed into, and that stdout is retrieved from.
 
-First, we need the receptor control service running in order to be able to start a kubernetes work unit. 
+First, we need the receptor control service running in order to be able to start a kubernetes work unit.
 
 .. code-block:: sh
 
     $ receptor -c foo.yml
-    DEBUG 2022/01/17 10:05:56 Listening on TCP [::]:2222                                          
-    INFO 2022/01/17 10:05:56 Running control service control                                      
-    INFO 2022/01/17 10:05:56 Initialization complete 
-   
+    DEBUG 2022/01/17 10:05:56 Listening on TCP [::]:2222
+    INFO 2022/01/17 10:05:56 Running control service control
+    INFO 2022/01/17 10:05:56 Initialization complete
+
 Now we can submit a kubernetes work unit.
 
 .. code-block:: yaml

docs/source/user_guide/tls.rst

@@ -6,7 +6,7 @@ mesh connections.
 
 .. contents::
    :local:
-   
+
 Configuring TLS
 ---------------
 
@@ -160,4 +160,4 @@ The default behaviour for this option is `false` which means that the certificat
 
     - tcp-peer:
         address: localhost:2222
-        tls: myclient
+        tls: myclient

docs/source/user_guide/workceptor.rst

@@ -1,5 +1,3 @@
-.. _workceptor:
-
 Workceptor
 ==========