diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29babe125..3df8df57b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,18 @@ Thank you for your interest in contributing to Jumpstarter! This document outlines the process for contributing to the project and provides guidelines to make the contribution process smooth. +## Getting Help + +If you have questions or need help, here are the best ways to connect with the community: + +### Community Resources + +- **Matrix Chat**: Join our [Matrix community](https://matrix.to/#/#jumpstarter:matrix.org) for real-time discussions and support +- **Weekly Meetings**: Participate in our [weekly community meetings](https://meet.google.com/gzd-hhbd-hpu) to discuss development and get help +- **Etherpad**: Check our [Etherpad](https://etherpad.jumpstarter.dev/pad-lister) for meeting notes and collaborative documentation +- **GitHub Issues**: [Open an issue](https://github.com/jumpstarter-dev/jumpstarter/issues) in the repository for bug reports and feature requests +- **Documentation**: Visit our [documentation](https://jumpstarter.dev/) for comprehensive guides and tutorials + ## Code of Conduct Please be respectful and considerate of others when contributing to the project. @@ -17,7 +29,7 @@ Please be respectful and considerate of others when contributing to the project. ## Development Setup -```bash +```shell # Install dependencies make sync @@ -59,13 +71,13 @@ If you are working on a driver or adapter library of general interest, please co To create a new driver scaffold, you can use the `create_driver.sh` script: -```bash +```shell ./__templates__/create_driver.sh vendor_name driver_name "Your Name" "your.email@example.com" ``` This will create the necessary files and structure for your driver in the `packages/` directory. For example: -```bash +```shell ./__templates__/create_driver.sh yepkit Ykush "Your Name" "your.email@example.com" ``` @@ -109,7 +121,7 @@ After creating your driver skeleton: To test your driver during development: -```bash +```shell # From the project root make sync # Synchronize dependencies cd packages/your_driver_package @@ -144,7 +156,7 @@ To contribute to the documentation, you'll need to set up your development envir To build and preview the documentation locally: -```bash +```shell cd docs make html # Build HTML documentation make docs-serve # Serve documentation locally for preview @@ -241,16 +253,6 @@ Once your documentation changes are complete: To add a new example: 1. Create a new directory in the `examples/` folder with a descriptive name -2. Include a comprehensive README.md with setup and usage instructions +2. Include a comprehensive `README.md` with setup and usage instructions 3. Follow the structure of existing examples 4. Ensure the example is well-documented and easy to follow - -## Getting Help - -If you have questions or need help, please: - -1. Check the [documentation](https://docs.jumpstarter.dev/) -2. Open an issue in the repository -3. Reach out to the maintainers - -Thank you for contributing to Jumpstarter! \ No newline at end of file diff --git a/README.md b/README.md index 810e6f559..6bde3b46a 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,50 @@ # ![bolt](./assets/bolt.svg) Jumpstarter -[![badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jumpstarter-dev/jumpstarter/main/assets/badge/v0.json)](https://github.com/jumpstarter-dev/jumpstarter) -[![ci](https://img.shields.io/github/actions/workflow/status/jumpstarter-dev/jumpstarter/build.yaml?branch=main&logo=github&label=CI)](https://github.com/jumpstarter-dev/jumpstarter/actions) -[![release](https://img.shields.io/github/v/release/jumpstarter-dev/jumpstarter)](https://github.com/jumpstarter-dev/jumpstarter/releases) -[![versions](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fjumpstarter-dev%2Fjumpstarter%2Fmain%2Fpackages%2Fjumpstarter%2Fpyproject.toml)](https://github.com/jumpstarter-dev/jumpstarter/blob/main/packages/jumpstarter/pyproject.toml) -[![license](https://img.shields.io/github/license/jumpstarter-dev/jumpstarter)](https://github.com/jumpstarter-dev/jumpstarter/blob/main/LICENSE) -[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) +[![Matrix](https://img.shields.io/matrix/jumpstarter%3Amatrix.org?color=blue)](https://matrix.to/#/#jumpstarter:matrix.org) +[![Etherpad](https://img.shields.io/badge/Etherpad-Notes-blue?logo=etherpad)](https://etherpad.jumpstarter.dev/pad-lister) +[![Community Meeting](https://img.shields.io/badge/Weekly%20Meeting-Google%20Meet-blue?logo=google-meet)](https://meet.google.com/gzd-hhbd-hpu) -An open source and cloud native Hardware-in-the-Loop testing tool that enables you to test your software stack on both real hardware and virtual environments using CI/CD principles. +A free, open source tool for automated testing on real and virtual hardware with CI/CD integration. Simplify device automation with consistent rules across local and distributed environments. ## Highlights -- πŸš€ A single, unified testing tool for local, virtual, and remote hardware testing. -- 🐍 Write test scripts in Python with familiar frameworks such as [pytest](https://docs.pytest.org/en/stable/). -- πŸ› οΈ Use [drivers](https://docs.jumpstarter.dev/introduction/drivers.html) to abstract complex hardware interfaces for testing. +- πŸš€ **Unified Testing** - One tool for local, virtual, and remote hardware +- 🐍 **Python-Powered** - Leverage Python's testing ecosystem +- πŸ› οΈ **Hardware Abstraction** - Simplify complex hardware interfaces with drivers - πŸ”Œ Built-in support for common interfaces such as [CAN](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-can), [IP](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-network), [GPIO](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-raspberrypi), [U-Boot](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-uboot), [SD Wire](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-sdwire), etc. -- πŸ’» Collaborate with developers around the world on shared test hardware. -- ☸ Integrates with your existing [Cloud Native](https://www.cncf.io/) development environment. -- πŸ”„ Run hardware tests with your existing CI/CD pipelines in the cloud. -- πŸ“¦ Support for containerized test runners with Podman/Docker. -- πŸ–₯️ Supports Linux and macOS. +- πŸ’» **Collaborative** - Share test hardware globally +- πŸ”„ **CI/CD Ready** - Works with cloud native developer environments and pipelines +- πŸ–₯️ **Cross-Platform** - Supports Linux and macOS ## Installation Install all the Jumpstarter Python components: -```console -pip install --extra-index-url https://docs.jumpstarter.dev/packages/simple jumpstarter-all +```shell +pip install --extra-index-url https://pkg.jumpstarter.dev/ jumpstarter-all ``` Or, just install the `jmp` CLI tool: -```console -pip install --extra-index-url https://docs.jumpstarter.dev/packages/simple jumpstarter-cli +```shell +pip install --extra-index-url https://pkg.jumpstarter.dev/ jumpstarter-cli ``` -To install the [Jumpstarter Service](https://docs.jumpstarter.dev/introduction/service.html) -in your Kubernetes cluster, see the [Service Installation](https://docs.jumpstarter.dev/installation/service/index.html) +To install the [Jumpstarter Service](https://jumpstarter.dev/introduction/service.html) +in your Kubernetes cluster, see the [Service Installation](https://jumpstarter.dev/installation/service/index.html) documentation. ## Documentation -Jumpstarter's documentation is available at [docs.jumpstarter.dev](https://docs.jumpstarter.dev). +Jumpstarter's documentation is available at [jumpstarter.dev](https://jumpstarter.dev). Additionally, the command line reference documentation can be viewed with `jmp --help`. ## Contributing Jumpstarter welcomes contributors of all levels of experience and would love to -see you involved in the project. See the [contributing guide](https://github.com/jumpstarter-dev/jumpstarter/blob/main/CONTRIBUTING.md) to get started. +see you involved in the project. See the [contributing guide](CONTRIBUTING.md) to get started. ## License -Jumpstarter is licensed under the Apache 2.0 License ([LICENSE](https://github.com/jumpstarter-dev/jumpstarter/blob/main/LICENSE) or [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)). +Jumpstarter is licensed under the Apache 2.0 License ([LICENSE](LICENSE) or [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)). diff --git a/__templates__/create_driver.sh b/__templates__/create_driver.sh index a9bb28753..abd3bc9dc 100755 --- a/__templates__/create_driver.sh +++ b/__templates__/create_driver.sh @@ -41,7 +41,7 @@ cat > "${README_FILE}" << 'EOF' ## Installation -```bash +```shell pip install jumpstarter-driver-${DRIVER_NAME} ``` diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index bed65c03f..fc690789e 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -5,4 +5,17 @@ /* Hide the Furo attribution text */ .made-with-furo { display: none !important; +} + +/* Fix version name overflow in sidebar */ +.sidebar-brand .sidebar-brand-text { + white-space: normal; + word-break: break-word; +} + +.sidebar-brand .sidebar-brand-text a { + display: inline-block; + max-width: 100%; + overflow: hidden; + text-overflow: ellipsis; } \ No newline at end of file diff --git a/docs/source/_static/img/logo-dark-theme.svg b/docs/source/_static/img/logo-dark-theme.svg index bcfae8c19..d3a8b971e 100644 --- a/docs/source/_static/img/logo-dark-theme.svg +++ b/docs/source/_static/img/logo-dark-theme.svg @@ -1,14 +1,83 @@ - - - - - - - - - - - - - + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/img/logo-light-theme.svg b/docs/source/_static/img/logo-light-theme.svg index 799bed8d0..e8e176989 100644 --- a/docs/source/_static/img/logo-light-theme.svg +++ b/docs/source/_static/img/logo-light-theme.svg @@ -1,14 +1,83 @@ - - - - - - - - - - - - - + + + + + + + + + + + + + + + + diff --git a/docs/source/_templates/head.html b/docs/source/_templates/head.html index a08b9962e..5dfbb93c3 100644 --- a/docs/source/_templates/head.html +++ b/docs/source/_templates/head.html @@ -1,4 +1,4 @@ - + + content="Jumpstarter: A free, open source tool for automated testing on real and virtual hardware with CI/CD integration. Simplify device automation with consistent rules across local and distributed environments." /> \ No newline at end of file diff --git a/docs/source/_templates/page.html b/docs/source/_templates/page.html index 794ebf576..692be9f7a 100644 --- a/docs/source/_templates/page.html +++ b/docs/source/_templates/page.html @@ -4,10 +4,13 @@ {% endblock %} {% block content %} +{% if pagename != 'index' %}

Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

+{% endif %} + {{ super() }} {% endblock %} diff --git a/docs/source/api-reference/drivers/dbus.md b/docs/source/api-reference/drivers/dbus.md index 76deb4877..952811798 100644 --- a/docs/source/api-reference/drivers/dbus.md +++ b/docs/source/api-reference/drivers/dbus.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-dbus ``` diff --git a/docs/source/api-reference/drivers/proxy.md b/docs/source/api-reference/drivers/proxy.md index 02eb006e9..dd7bacf82 100644 --- a/docs/source/api-reference/drivers/proxy.md +++ b/docs/source/api-reference/drivers/proxy.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-proxy ``` diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 916ec0ea1..2a6ae7c4e 100644 --- a/docs/source/architecture.md +++ b/docs/source/architecture.md @@ -115,7 +115,7 @@ virtual devices. #### Example: Running Local Tests -```bash +```shell jmp shell --exporter my-hardware-exporter jmp shell --exporter my-virtual-exporter @@ -193,7 +193,7 @@ environments and prevents unauthorized access to hardware resources. #### Example: Running Distributed Tests -```bash +```shell # Configure client with server information jmp config client use my-client diff --git a/docs/source/cli/clients.md b/docs/source/cli/clients.md index 96318e419..8c0e390b4 100644 --- a/docs/source/cli/clients.md +++ b/docs/source/cli/clients.md @@ -18,7 +18,7 @@ You can also use the following options to specify the kubeconfig and context to To create a new client and its associated config, run the following command: -```bash +```shell $ jmp admin create client john --namespace jumpstarter-lab --unsafe -o john.yaml ``` @@ -69,13 +69,13 @@ system is using self-signed certificates. name: my-client ``` - ```bash + ```shell $ kubectl apply -f my-client.yaml ``` 2. Retrieve the created client resource information: - ```bash + ```shell $ kubectl get client my-client -o yaml $ kubectl get client my-client -o=jsonpath='{.status.endpoint}' $ kubectl get secret $(kubectl get client my-client -o=jsonpath='{.status.credential.name}') -o=jsonpath='{.data.token}' | base64 -d @@ -86,7 +86,7 @@ system is using self-signed certificates. The end user can then configure their client using the [jmp](./reference/jmp.md#jmp-cli-reference) CLI: - ```bash + ```shell $ jmp config client create my-client Enter a valid Service endpoint: devl.jumpstarter.dev Enter a Jumpstarter auth token (hidden): *** diff --git a/docs/source/cli/exporters.md b/docs/source/cli/exporters.md index fd9c9969d..c9bb3ac09 100644 --- a/docs/source/cli/exporters.md +++ b/docs/source/cli/exporters.md @@ -17,7 +17,7 @@ registered. Exporter creation must be done by an administrator user who has access to the Kubernetes cluster where the `jumpstarter-controller` service is hosted. -```bash +```shell # Create the exporter instance $ jmp admin create exporter my-exporter --namespace jumpstarter-lab -o my-exporter.yaml ``` diff --git a/docs/source/cli/run-tests.md b/docs/source/cli/run-tests.md index 28472617e..5710b629a 100644 --- a/docs/source/cli/run-tests.md +++ b/docs/source/cli/run-tests.md @@ -14,7 +14,7 @@ to authenticate with the Service. Alternatively the client can receive the endpoint and token as environment variables: -```bash +```shell export JMP_ENDPOINT=jumpstarter.my-lab.com:1443 export JMP_TOKEN=dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz ``` diff --git a/docs/source/conf.py b/docs/source/conf.py index d92d8226d..80e366d3e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,7 +15,7 @@ project = "jumpstarter" copyright = "2025, Jumpstarter Contributors" -author = "Jumpstarter Community" +author = "Jumpstarter Contributors" controller_version = requests.get( "https://quay.io/api/v1/repository/jumpstarter-dev/helm/jumpstarter/tag/", params={"limit": 1} @@ -44,7 +44,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "furo" -html_title = "Jumpstarter Docs" +html_title = "Jumpstarter Documentation" html_logo = "_static/img/logo-light-theme.svg" html_favicon = "_static/img/favicon.png" html_show_sphinx = False @@ -86,12 +86,25 @@ # This replaces the custom bash script approach with built-in functionality # Tags pattern for html_context["versions"] -smv_tag_whitelist = r"^main$|^v(0\.[5-9](\.\d+)|0\.[1-9][0-9]+(\.\d+)|[1-9]\d*\.\d+\.\d+)$" # Starting from v0.5.0 +smv_tag_whitelist = r"^v(0\.[5-9](\.\d+)|0\.[1-9][0-9]+(\.\d+)|[1-9]\d*\.\d+\.\d+)$" # Starting from v0.5.0 smv_branch_whitelist = r"^(main|master)$" # Only include main/master branch smv_remote_whitelist = None smv_released_pattern = r"^v[0-9]+\.[0-9]+\.[0-9]+$" # Tags that are considered releases smv_outputdir_format = "{ref.name}" # Directory name format +# Ensure static files are copied to all versions +smv_static_files = [ + "_static/**", + "_templates/**", +] + +# Ensure RST directives are processed +smv_include_patterns = [ + "*.md", + "*.rst", + "*.txt", +] + # Patterns for the versions panel html_context = { "display_lower": True, # Display lower versions at the bottom of the menu diff --git a/docs/source/config/cli.md b/docs/source/config/cli.md index 435822bfc..8afc624e5 100644 --- a/docs/source/config/cli.md +++ b/docs/source/config/cli.md @@ -94,14 +94,14 @@ config file. To switch between different client configs, use the `jmp config client use ` command: -```bash +```shell $ jmp config client use another Using client config '/home/jdoe/.config/jumpstarter/clients/another.yaml' ``` All client configurations can be listed with `jmp config client list`: -```bash +```shell $ jmp config client list CURRENT NAME ENDPOINT PATH * default jumpstarter1.my-lab.com:1443 /home/jdoe/.config/jumpstarter/clients/default.yaml @@ -111,7 +111,7 @@ CURRENT NAME ENDPOINT PATH Clients can also be removed using `jmp config client delete `: -```bash +```shell $ jmp config client delete myclient Deleted client config '/home/jdoe/.config/jumpstarter/clients/myclient.yaml' ``` @@ -210,7 +210,7 @@ CLI](../cli/exporters.md). To create a new exporter configuration file from a know endpoint and token the `jmp config exporter create ` command can be used. -```bash +```shell $ jmp config exporter create myexporter Endpoint: grpc.jumpstarter.my.domain.com Token: <> @@ -218,20 +218,20 @@ Token: <> To use a specific config when starting the exporter: -```bash +```shell $ jmp run --exporter my-exporter Using exporter config '/etc/jumpstarter/exporters/another/exporter.yaml' ``` The path to a config can also be provided: -```bash +```shell jmp run --exporter-config /etc/jumpstarter/exporters/another/exporter.yaml ``` All exporter configurations can be listed with `jmp config exporter list`: -```bash +```shell $ jmp config exporter list ALIAS PATH test-exporter-2 /etc/jumpstarter/exporters/test-exporter-2.yaml @@ -240,7 +240,7 @@ my-exporter /etc/jumpstarter/exporters/my-exporter.yaml Exporters can also be removed using `jmp config exporter delete `: -```bash +```shell $ jmp config exporter delete myexporter Deleted exporter config '/etc/jumpstarter/exporters/myexporter.yaml' ``` @@ -323,7 +323,7 @@ WantedBy=multi-user.target default.target Then enable and start the service: -```bash +```shell sudo systemctl daemon-reload sudo systemctl enable --now my-exporter ``` diff --git a/docs/source/getting-started/setup-exporter-client.md b/docs/source/getting-started/setup-exporter-client.md index 955646286..5ee02f2ce 100644 --- a/docs/source/getting-started/setup-exporter-client.md +++ b/docs/source/getting-started/setup-exporter-client.md @@ -28,7 +28,7 @@ admin` CLI provides methods to interact with the controller directly. To create an exporter and save the configuration locally, run the following command: -```bash +```shell # Creates an exporter called "testing" and saves the config $ jmp admin create exporter testing --save ``` @@ -46,7 +46,7 @@ Once the exporter has been created, a new configuration file will be saved to To edit the configuration file with your default text editor, run the following command: -```bash +```shell # Opens the config for "testing" in your default editor $ jmp config exporter edit testing ``` @@ -75,7 +75,7 @@ To run the exporter locally, we can use the `jmp` CLI tool. Run the following command to start the exporter locally using the configuration file: -```bash +```shell # Runs the exporter "testing" locally $ jmp run --exporter testing ``` @@ -88,7 +88,7 @@ is closed. To connect to the new exporter, a client must be created. We can also use the `jmp admin` CLI tool to create a client using the controller. -```bash +```shell # This will create a client called "hello", allow unsafe drivers, and save the config $ jmp admin create client hello --save --unsafe ``` @@ -105,7 +105,7 @@ functionality within the `jmp` CLI. When a shell is spawned, the client attempts to acquire a lease on an exporter. Once the lease is acquired, the client can be interacted with through the magic `j` command or via the Python API. -```bash +```shell # Spawn a shell using the "hello" client $ jmp shell --client hello --selector example.com/board=foo ``` @@ -118,7 +118,7 @@ $ jmp shell --client hello --selector example.com/board=foo Once a lease is acquired, we can interact with the drivers hosted by the exporter within the shell instance. -```bash +```shell # Spawn a shell using the "hello" client $ jmp shell --client hello --selector example.com/board=foo diff --git a/docs/source/index.md b/docs/source/index.md index 7068cf265..20ed71075 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,10 +1,33 @@ # Welcome to Jumpstarter -Jumpstarter is a free and open-source testing tool that enables you to test your software stack on both real hardware and virtual environments using CI/CD principles. It provides powerful testing tools that leverage Cloud Native principles, modern CI/CD technologies, and open standards for the next generation of edge devices, whether physical or emulated. +```{eval-rst} +.. image:: https://img.shields.io/badge/GitHub-Repository-blue?logo=github + :target: https://github.com/jumpstarter-dev/jumpstarter + :alt: GitHub Repository + +.. image:: https://img.shields.io/badge/PyPI-Packages-blue?logo=pypi + :target: https://pypi.org/project/jumpstarter/ + :alt: Python Packages + +.. image:: https://img.shields.io/matrix/jumpstarter%3Amatrix.org?color=blue + :target: https://matrix.to/#/#jumpstarter:matrix.org + :alt: Matrix Chat + +.. image:: https://img.shields.io/badge/Etherpad-Notes-blue?logo=etherpad + :target: https://etherpad.jumpstarter.dev/pad-lister + :alt: Etherpad Notes + +.. image:: https://img.shields.io/badge/Weekly%20Meeting-Google%20Meet-blue?logo=google-meet + :target: https://meet.google.com/gzd-hhbd-hpu + :alt: Weekly Meeting +``` -## Device Automation Made Simple +Jumpstarter is a free and open source testing tool that bridges the gap between development workflows and deployment environments. It enables you to test your software stack consistently across both real hardware and virtual environments using cloud native principles. By decoupling your target devices (physical or virtual) from test runners, development machines, and CI/CD pipelines, Jumpstarter allows you to use the same automation scripts everywhere - like a *Makefile* for device automation. -Jumpstarter decouples your target devices (physical or virtual) from test runners, development machines, and CI/CD pipelines, allowing you to use the same automation scripts, commands, and processes everywhere. Think of it as a *Makefile* for device automation that can run locally on your machine or distributed across your infrastructure. +```{include} ../../README.md +:start-after: "## Highlights" +:end-before: "##" +``` ## Learning Paths @@ -47,10 +70,4 @@ solution-architecture.md contributing.md glossary.md api-reference/index.md -``` - -## Resources - -```{eval-rst} -* `Python Packages <./packages/index.html>`_ -``` +``` \ No newline at end of file diff --git a/docs/source/installation/python-package.md b/docs/source/installation/python-package.md index ecd5f3201..8fc3d9c24 100644 --- a/docs/source/installation/python-package.md +++ b/docs/source/installation/python-package.md @@ -2,15 +2,15 @@ ## Release install -The [Jumpstarter Python packages](https://docs.jumpstarter.dev/packages/) +The [Jumpstarter Python packages](https://pkg.jumpstarter.dev/) contain all the necessary tools to run an exporter or interact with your hardware as a client. The Python package can be installed using ``pip`` or similar. Python {{requires_python}} is required: -```bash -$ pip3 install --extra-index-url https://docs.jumpstarter.dev/packages/simple jumpstarter-all +```shell +$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/ jumpstarter-all $ mkdir -p "${HOME}/.config/jumpstarter/" $ sudo mkdir /etc/jumpstarter @@ -37,7 +37,7 @@ We perform basic e2e testing and thorough unit testing, so we recommend installing the latest version from the `main` branch. For this, you will need a few tools like `uv`, `make`, and `git`: -```bash +```shell $ sudo dnf install -y uv make git # Clone the repository @@ -57,7 +57,7 @@ $ sudo mkdir /etc/jumpstarter Then you can use the Jumpstarter CLI commands by activating the Python virtual environment: -```bash +```shell $ source .venv/bin/activate $ jmp version ``` @@ -90,7 +90,7 @@ $ alias jmp='podman run --rm -it -w /home \ Then you can try: -```bash +```shell $ jmp config client list CURRENT NAME ENDPOINT PATH * default grpc.devel.jumpstarter.dev:443 /root/.config/jumpstarter/clients/default.yaml diff --git a/docs/source/installation/service/kind-helm.md b/docs/source/installation/service/kind-helm.md index e8fd0d01c..d44e0e65e 100644 --- a/docs/source/installation/service/kind-helm.md +++ b/docs/source/installation/service/kind-helm.md @@ -56,7 +56,7 @@ nodes: Next, create a kind cluster using the config you created. -```bash +```shell kind create cluster --config kind_config.yaml ``` diff --git a/docs/source/installation/service/minikube-helm.md b/docs/source/installation/service/minikube-helm.md index 325a7165a..b91559f66 100644 --- a/docs/source/installation/service/minikube-helm.md +++ b/docs/source/installation/service/minikube-helm.md @@ -17,7 +17,7 @@ website](https://minikube.sigs.k8s.io/docs/start/). First, we must start a local minikube cluster with the correct features enabled to support Jumpstarter. -```bash +```shell # We must expand the default NodePort range to include the Jumpstarter ports minikube start --extra-config=apiserver.service-node-port-range=8000-9000 ``` diff --git a/docs/source/installation/service/openshift-argocd.md b/docs/source/installation/service/openshift-argocd.md index 4828fa052..0a467f611 100644 --- a/docs/source/installation/service/openshift-argocd.md +++ b/docs/source/installation/service/openshift-argocd.md @@ -8,7 +8,7 @@ manage the resources in the namespace. In this case, using the default openshift-gitops ArgoCD deployment, the command would be: -```bash +```shell kubectl create namespace jumpstarter-lab kubectl label namespace jumpstarter-lab argocd.argoproj.io/managed-by=openshift-gitops ``` diff --git a/docs/source/introduction/adapters.md b/docs/source/introduction/adapters.md index b69a07f7f..96691479a 100644 --- a/docs/source/introduction/adapters.md +++ b/docs/source/introduction/adapters.md @@ -13,4 +13,11 @@ Adapters in Jumpstarter follow a transformation pattern where: For comprehensive documentation on the adapter architecture, including detailed patterns and examples, see the [Adapter Classes and Architecture](../api-reference/adapters.md) reference. -Unlike [Drivers](./drivers.md), which establish the foundational connections to hardware or virtual interfaces, adapters focus on providing alternative ways to interact with those connections without modifying the underlying drivers. \ No newline at end of file +Unlike [Drivers](./drivers.md), which establish the foundational connections to hardware or virtual interfaces, adapters focus on providing alternative ways to interact with those connections without modifying the underlying drivers. + +## Types of Adapters + +```{include} ../api-reference/adapters/index.md +:start-after: "## Types of Adapters" +:end-before: "```{toctree}" +``` \ No newline at end of file diff --git a/docs/source/introduction/exporters.md b/docs/source/introduction/exporters.md index 0e72e6f1c..67becd268 100644 --- a/docs/source/introduction/exporters.md +++ b/docs/source/introduction/exporters.md @@ -63,7 +63,7 @@ To run an Exporter on a host system, you must have Python {{requires_python}} installed and the driver packages specified in the config installed in your current Python environment. -```bash +```shell # Run the exporter myexporter in your local terminal $ jmp run --exporter myexporter ``` diff --git a/docs/source/introduction/index.md b/docs/source/introduction/index.md index be80acbe8..c15df0beb 100644 --- a/docs/source/introduction/index.md +++ b/docs/source/introduction/index.md @@ -1,13 +1,13 @@ # Introduction -Jumpstarter is a free and open-source testing tool that enables you to test your +Jumpstarter is a free and open source testing tool that enables you to test your software stack on both real hardware and virtual environments using CI/CD principles. Automated testing with physical hardware (Hardware-in-the-Loop or HiL) and virtual devices has been established for years in industries such as automotive and manufacturing. However, these tools are often expensive and inaccessible to -hobbyists and open-source projects. +hobbyists and open source projects. Jumpstarter provides powerful testing tools that leverage [Cloud Native](https://www.cncf.io/) principles, modern CI/CD technologies, and open diff --git a/examples/soc-pytest/README.md b/examples/soc-pytest/README.md index ebc739f50..9c7dffc28 100644 --- a/examples/soc-pytest/README.md +++ b/examples/soc-pytest/README.md @@ -22,7 +22,7 @@ This example requires the following hardware: 3) Label the exporter in k8s with the `board=rpi4` label 4) Prepare the images by running `make` in the `image` directory 5) Run the tests in this directory by running: -```bash +```shell $ cd jumpstarter_example_soc_pytest $ uv run pytest -s ================================================================== test session starts =================================================================== diff --git a/examples/soc-pytest/jumpstarter_example_soc_pytest/image/README.md b/examples/soc-pytest/jumpstarter_example_soc_pytest/image/README.md index e65006975..64d6e6e02 100644 --- a/examples/soc-pytest/jumpstarter_example_soc_pytest/image/README.md +++ b/examples/soc-pytest/jumpstarter_example_soc_pytest/image/README.md @@ -11,7 +11,7 @@ You will need guestmount installed, sudo permissions. fuse must be configured to enable `user_allow_other` in `/etc/fuse.conf`. -```bash +```shell $ make make download-image make[1]: Entering directory '/home/majopela/jumpstarter/examples/soc-pytest/jumpstarter_example_soc_pytest/image' diff --git a/packages/jumpstarter-driver-can/README.md b/packages/jumpstarter-driver-can/README.md index 4d48582ac..18e17e240 100644 --- a/packages/jumpstarter-driver-can/README.md +++ b/packages/jumpstarter-driver-can/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-can ``` diff --git a/packages/jumpstarter-driver-corellium/README.md b/packages/jumpstarter-driver-corellium/README.md index fb72879f2..e34a0fb89 100644 --- a/packages/jumpstarter-driver-corellium/README.md +++ b/packages/jumpstarter-driver-corellium/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-corellium ``` diff --git a/packages/jumpstarter-driver-dutlink/README.md b/packages/jumpstarter-driver-dutlink/README.md index 7c28cdffe..f0ca42dea 100644 --- a/packages/jumpstarter-driver-dutlink/README.md +++ b/packages/jumpstarter-driver-dutlink/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-dutlink ``` diff --git a/packages/jumpstarter-driver-flashers/README.md b/packages/jumpstarter-driver-flashers/README.md index 526a583f7..3c4ce0d48 100644 --- a/packages/jumpstarter-driver-flashers/README.md +++ b/packages/jumpstarter-driver-flashers/README.md @@ -88,7 +88,7 @@ This doesn't work with sphinx-click, so we'll just use the raw CLI :nested: full ``` --> -```bash +```shell $ jmp shell -l board=ti-03 INFO:jumpstarter.client.lease:Created lease request for labels {'board': 'ti-03'} for 0:30:00 jumpstarter ⚑remote ➀ j storage @@ -107,7 +107,7 @@ Commands: ``` ### flash -```bash +```shell Usage: j storage flash [OPTIONS] FILE Flash image to DUT from file @@ -156,7 +156,7 @@ BaseFlasherClient - INFO - Powering off target ``` ### bootloader-shell -```bash +```shell Usage: j storage bootloader-shell [OPTIONS] Start a uboot/bootloader interactive console @@ -181,7 +181,7 @@ gcc (GCC) 11.4.1 20231218 (Red Hat 11.4.1-3) GNU ld version 2.35.2-42.el9 ``` ### busybox-shell -```bash +```shell Usage: j storage busybox-shell [OPTIONS] Start a busybox interactive console diff --git a/packages/jumpstarter-driver-http/README.md b/packages/jumpstarter-driver-http/README.md index 78b5221fb..cf1c7f200 100644 --- a/packages/jumpstarter-driver-http/README.md +++ b/packages/jumpstarter-driver-http/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-http ``` diff --git a/packages/jumpstarter-driver-network/README.md b/packages/jumpstarter-driver-network/README.md index ce972ce92..5c08df208 100644 --- a/packages/jumpstarter-driver-network/README.md +++ b/packages/jumpstarter-driver-network/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-network ``` diff --git a/packages/jumpstarter-driver-opendal/README.md b/packages/jumpstarter-driver-opendal/README.md index 192cb30ec..8639d8a3f 100644 --- a/packages/jumpstarter-driver-opendal/README.md +++ b/packages/jumpstarter-driver-opendal/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-opendal ``` diff --git a/packages/jumpstarter-driver-power/README.md b/packages/jumpstarter-driver-power/README.md index 4cad4211f..f599e3555 100644 --- a/packages/jumpstarter-driver-power/README.md +++ b/packages/jumpstarter-driver-power/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-power ``` diff --git a/packages/jumpstarter-driver-probe-rs/README.md b/packages/jumpstarter-driver-probe-rs/README.md index fa0e6a6b5..567a03a72 100644 --- a/packages/jumpstarter-driver-probe-rs/README.md +++ b/packages/jumpstarter-driver-probe-rs/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-probe-rs ``` diff --git a/packages/jumpstarter-driver-pyserial/README.md b/packages/jumpstarter-driver-pyserial/README.md index 1ea378aad..25b30a44d 100644 --- a/packages/jumpstarter-driver-pyserial/README.md +++ b/packages/jumpstarter-driver-pyserial/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-pyserial ``` diff --git a/packages/jumpstarter-driver-qemu/README.md b/packages/jumpstarter-driver-qemu/README.md index 388ff1823..d9690e902 100644 --- a/packages/jumpstarter-driver-qemu/README.md +++ b/packages/jumpstarter-driver-qemu/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-qemu ``` diff --git a/packages/jumpstarter-driver-raspberrypi/README.md b/packages/jumpstarter-driver-raspberrypi/README.md index fa47ba740..7edeb906c 100644 --- a/packages/jumpstarter-driver-raspberrypi/README.md +++ b/packages/jumpstarter-driver-raspberrypi/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-raspberrypi ``` diff --git a/packages/jumpstarter-driver-sdwire/README.md b/packages/jumpstarter-driver-sdwire/README.md index dfb6c2e43..11dd8450d 100644 --- a/packages/jumpstarter-driver-sdwire/README.md +++ b/packages/jumpstarter-driver-sdwire/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-sdwire ``` diff --git a/packages/jumpstarter-driver-shell/README.md b/packages/jumpstarter-driver-shell/README.md index eab6a067f..68cd209f7 100644 --- a/packages/jumpstarter-driver-shell/README.md +++ b/packages/jumpstarter-driver-shell/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-shell ``` diff --git a/packages/jumpstarter-driver-snmp/README.md b/packages/jumpstarter-driver-snmp/README.md index c7b72d605..f42177fea 100644 --- a/packages/jumpstarter-driver-snmp/README.md +++ b/packages/jumpstarter-driver-snmp/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-snmp ``` @@ -66,7 +66,7 @@ snmp_client.on() ``` Using the CLI: -```bash +```shell j power on j power off j power cycle --wait 3 diff --git a/packages/jumpstarter-driver-tftp/README.md b/packages/jumpstarter-driver-tftp/README.md index 3728e5e29..c35043e03 100644 --- a/packages/jumpstarter-driver-tftp/README.md +++ b/packages/jumpstarter-driver-tftp/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-tftp ``` diff --git a/packages/jumpstarter-driver-uboot/README.md b/packages/jumpstarter-driver-uboot/README.md index 346cf4939..41392bff2 100644 --- a/packages/jumpstarter-driver-uboot/README.md +++ b/packages/jumpstarter-driver-uboot/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-uboot ``` diff --git a/packages/jumpstarter-driver-ustreamer/README.md b/packages/jumpstarter-driver-ustreamer/README.md index e4eaa7c0f..e25bc2882 100644 --- a/packages/jumpstarter-driver-ustreamer/README.md +++ b/packages/jumpstarter-driver-ustreamer/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-ustreamer ``` diff --git a/packages/jumpstarter-driver-yepkit/README.md b/packages/jumpstarter-driver-yepkit/README.md index fdc2c9ca2..218cd672e 100644 --- a/packages/jumpstarter-driver-yepkit/README.md +++ b/packages/jumpstarter-driver-yepkit/README.md @@ -4,7 +4,7 @@ ## Installation -```bash +```shell pip install jumpstarter-driver-yepkit ``` @@ -55,7 +55,7 @@ client.power.off() ### CLI access -```bash +```shell $ sudo ~/.cargo/bin/uv run jmp shell --exporter-config ./packages/jumpstarter-driver-yepkit/examples/exporter.yaml WARNING:Ykush:No serial number provided for ykush, using the first one found: YK25838 INFO:Ykush:Power OFF for Ykush YK25838 on port 1