[PXCT-1779] brick docs rework

[swikstrom]

What This PR Changes

• expand and restructure bricks documentation

Todo

• Verify that the custom brick example code blocks reflect the downloadable archives (https://content.arduino.cc/assets/simple-web-server-brick.zip and https://content.arduino.cc/assets/simple-device-access-brick.zip)

Contribution Guidelines

• I confirm that I have read the contribution guidelines and comply with them.

[per1234]

Suggested change

	image: custom_registry/my_service:latest
	image: some_registry/some_image:latest

• Adjust placeholder reference components to avoid giving the false impression that use of an image created by the user is required. Existing images may also be utilized in custom Bricks.
• Use correct "image" term (reference).

[swikstrom]

I've applied the feedback in 466cedd

[swikstrom]

@per1234 In addition to the example with placeholder components, do you think we should include some real examples?

For example, the one you shared here:

services:
  player:
    image: debian:bookworm-slim
    command: sh -c "ls -l /dev/snd || true; sleep infinity"
    devices:
      - /dev/snd

[per1234]

do you think we should include some real examples?

Great idea! I think that would be very helpful to the reader.

For example, the one you shared here

That Compose file was intended only for use directly with Docker for troubleshooting. It doesn't provide an interface that can be used by the Python script of an App.

I suggest providing two demonstrations, one for each fundamental concept:

• Use of a container
• Giving the container access to system resources

Use of a container

services:
  hello_server:
    # Create a container from a Docker image that provides the BSD Netcat networking utility.
    image: toolbelt/netcat
    # Use Netcat to create a web server that responds with a simple message.
    # See: https://manpages.debian.org/unstable/netcat-openbsd/nc.1.en.html
    entrypoint: |
      sh -c ' \
        while true; do
          echo -e "HTTP/1.1 200 OK\r\n\r\nHello, world!" \
          | \
            nc -l -p 5000 -q 0 -v
        done \
      '
    ports:
      # Expose the port for communication with the container's web server.
      # See: https://docs.docker.com/reference/compose-file/services/#ports
      - 5000

This Brick provides an interface that can be used from the Python code running on the App's primary container:

import requests

from arduino.app_utils import App

response = requests.get("http://hello_server:5000")
print("Web server response:", response.text)

App.run()

Here is a complete demonstration App:

simple-web-server-brick.zip

Giving the container access to system resources

# See: https://docs.docker.com/reference/compose-file/services/
services:
  sound_devices:
    # Create a container from a Docker image that provides the BSD Netcat networking utility.
    image: toolbelt/netcat
    # Make the host system's sound devices available for use inside the container.
    devices:
      - /dev/snd
    # Use Netcat to create a web server that responds with a list of the sound devices present in the container.
    # See: https://manpages.debian.org/unstable/netcat-openbsd/nc.1.en.html
    entrypoint: |
      sh -c ' \
        while true; do
          sound_devices="$$(ls -1 /dev/snd)"

          echo -e "HTTP/1.1 200 OK\r\n\r\n$$sound_devices" \
          | \
            nc -l -p 5000 -q 0 -v
        done \
      '
    ports:
      # Expose the port for communication with the container's web server.
      # See: https://docs.docker.com/reference/compose-file/services/#ports
      - 5000

Minimal Python code to interact with the Brick from the App's primary container:

import requests

from arduino.app_utils import App

# Make an HTTP request to the custom Brick's web server.
# See: https://requests.readthedocs.io/en/latest/user/quickstart/#make-a-request
response = requests.get("http://sound_devices:5000")
print("Sound devices:")
print(response.text)

App.run()

Demonstration App:

simple-device-access-brick.zip

[swikstrom]

Thanks Per! These examples are great. My learning preference is definitely to modify and experiment rather than read documentation and implement from scratch. I'm sure many users feel the same way 😄

I added a new "Custom Brick Examples" section.

[swikstrom]

Sorry @per1234 , I completely overlooked your comments when closing this PR.

The scope of this task expanded to include a deeper rework of the Bricks documentation (unfortunately, taking longer than expected).

I've reopened the PR and will now address your comments!

[github-actions]

Preview Deployment

Waiting for deployment to complete...

[swikstrom]

@per1234 Kubernetes documentation seems to use "primary container" and "main container" interchangeably. Given the main.py filename, I think that "main container" would be a more consistent terminology.

Suggested change

	This Brick provides an interface that can be used from the Python code running on the App's primary container:
	This Brick provides an interface that can be used from the Python code running on the App's main container:

[swikstrom]

Suggested change

	Minimal Python code to interact with the Brick from the App's primary container:
	Minimal Python code to interact with the Brick from the App's main container:

@per1234 Same as for https://github.com/arduino/docs-content/pull/2944/changes#r3493608128.