From 2f0ea9f8b5c48d3904306d306103753062b8dd7e Mon Sep 17 00:00:00 2001 From: Thom Carlin Date: Wed, 21 Feb 2024 11:12:43 -0500 Subject: [PATCH] Fix Sphinx issues with documentation (#953) --- docs/source/contributing.rst | 9 +- docs/source/developer_guide.rst | 86 +++++++++---------- docs/source/installation.rst | 2 +- docs/source/user_guide/basic_usage.rst | 1 + docs/source/user_guide/edge_networks.rst | 2 +- docs/source/user_guide/index.rst | 2 +- .../user_guide/interacting_with_nodes.rst | 4 +- docs/source/user_guide/k8s.rst | 10 +-- docs/source/user_guide/tls.rst | 4 +- docs/source/user_guide/workceptor.rst | 2 - 10 files changed, 61 insertions(+), 61 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 9c113bec4..e4fead86f 100644 --- a/docs/source/contributing.rst +++ b/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 `_ 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 ``_ @@ -36,4 +34,7 @@ After the release is published, the `Promote Release `_. .. note:: - If you need to re-run `Stage Release `_ 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 + diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index 9dfe96c00..ff303ec04 100644 --- a/docs/source/developer_guide.rst +++ b/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`). diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 4025e9a2b..9e73755e1 100644 --- a/docs/source/installation.rst +++ b/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. \ No newline at end of file +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 index ce31b2528..a9ab5d482 100644 --- a/docs/source/user_guide/basic_usage.rst +++ b/docs/source/user_guide/basic_usage.rst @@ -2,6 +2,7 @@ Using Receptor =============== . contents:: + :local: Configuring Receptor with the CLI diff --git a/docs/source/user_guide/edge_networks.rst b/docs/source/user_guide/edge_networks.rst index eaf9068da..24af09ad9 100644 --- a/docs/source/user_guide/edge_networks.rst +++ b/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. \ No newline at end of file +*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. diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst index 2595f0810..0c615e435 100644 --- a/docs/source/user_guide/index.rst +++ b/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. diff --git a/docs/source/user_guide/interacting_with_nodes.rst b/docs/source/user_guide/interacting_with_nodes.rst index 3292a8da6..14c4ee2e1 100644 --- a/docs/source/user_guide/interacting_with_nodes.rst +++ b/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", diff --git a/docs/source/user_guide/k8s.rst b/docs/source/user_guide/k8s.rst index 1f4e7c236..b36ce6709 100644 --- a/docs/source/user_guide/k8s.rst +++ b/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 diff --git a/docs/source/user_guide/tls.rst b/docs/source/user_guide/tls.rst index be9aee172..a4cf9bbb8 100644 --- a/docs/source/user_guide/tls.rst +++ b/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 \ No newline at end of file + tls: myclient diff --git a/docs/source/user_guide/workceptor.rst b/docs/source/user_guide/workceptor.rst index b84af0e38..e9c6183b7 100644 --- a/docs/source/user_guide/workceptor.rst +++ b/docs/source/user_guide/workceptor.rst @@ -1,5 +1,3 @@ -.. _workceptor: - Workceptor ==========