From d9088fab5b022ed4f25feb506ef201a3ebca6224 Mon Sep 17 00:00:00 2001 From: Lucy Cifferello <12953208+elvece@users.noreply.github.com> Date: Thu, 24 Feb 2022 14:38:46 -0700 Subject: [PATCH] update dev docs titles, spacing, properties content --- site/source/developer-docs/advanced/index.rst | 2 +- .../build-package-example/01_setup.rst | 26 +++++++------- .../03_hardware-compile.rst | 6 ++-- .../build-package-example/04_docker-build.rst | 6 ++-- .../build-package-example/07_create-s9pk.rst | 6 ++-- .../09_create-wrapper.rst | 6 ++-- .../10_install-package.rst | 30 ++++++++-------- .../build-package-example/resources.rst | 16 ++++----- .../getting-started/environment-setup.rst | 6 ++-- .../developer-docs/getting-started/index.rst | 2 +- .../getting-started/quick-start.rst | 36 +++++++++---------- .../developer-docs/getting-started/sdk.rst | 30 ++++++++-------- .../specification/properties.rst | 13 +++++-- site/source/index.rst | 2 +- sphinx-scylladb-theme | 2 +- 15 files changed, 99 insertions(+), 90 deletions(-) diff --git a/site/source/developer-docs/advanced/index.rst b/site/source/developer-docs/advanced/index.rst index ec31a3d..3672013 100644 --- a/site/source/developer-docs/advanced/index.rst +++ b/site/source/developer-docs/advanced/index.rst @@ -36,7 +36,7 @@ This section included advanced commands for working with packages in EmbassyOS. .. This is for the side navigation display .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :hidden: dev-tools/index \ No newline at end of file diff --git a/site/source/developer-docs/build-package-example/01_setup.rst b/site/source/developer-docs/build-package-example/01_setup.rst index 9ac5b56..dbb3e38 100644 --- a/site/source/developer-docs/build-package-example/01_setup.rst +++ b/site/source/developer-docs/build-package-example/01_setup.rst @@ -1,19 +1,19 @@ -.. _packaging-setup: +.. _packaging-framework: -========================== -Step 1 - Context and Setup -========================== +================== +Step 1 - Framework +================== What we'll build ---------------- We'll create a web application that produces a hello world page. This web application will be the service we package for the Embassy. During this guide we will: -1. Create a simple hello world web service -2. Create a Dockerfile -3. Create a Package Manifest -4. Create a hosted repository which will contain all the service components -5. Create the packaged service file + 1. Create a simple hello world web service + 2. Create a Dockerfile + 3. Create a Package Manifest + 4. Create a hosted repository which will contain all the service components + 5. Create the packaged service file You can find the `complete code `_ referenced in this guide on GitHub. @@ -22,9 +22,9 @@ Download required tools If necessary, download any of the system requirements: -- Docker -- EmbassySDK -- A code editor -- Terminal + - Docker + - EmbassySDK + - A code editor + - Terminal For more details and installation steps for these tools, visit the :ref:`environment setup ` page. diff --git a/site/source/developer-docs/build-package-example/03_hardware-compile.rst b/site/source/developer-docs/build-package-example/03_hardware-compile.rst index 4e6ff72..15fc377 100644 --- a/site/source/developer-docs/build-package-example/03_hardware-compile.rst +++ b/site/source/developer-docs/build-package-example/03_hardware-compile.rst @@ -1,8 +1,8 @@ .. _packaging-compile-raspi: -=========================== -Step 3 - Build for Hardware -=========================== +======================= +Step 3 - Hardware Build +======================= EmbassyOS is run on the arm-v8 architecture, specifically the aarch64 state, for the RaspberryPi. diff --git a/site/source/developer-docs/build-package-example/04_docker-build.rst b/site/source/developer-docs/build-package-example/04_docker-build.rst index 0f12338..5ea0ba9 100644 --- a/site/source/developer-docs/build-package-example/04_docker-build.rst +++ b/site/source/developer-docs/build-package-example/04_docker-build.rst @@ -1,8 +1,8 @@ .. _packaging-docker-build: -========================== -Step 4 - Build with Docker -========================== +===================== +Step 4 - Docker Build +===================== Now that we have our code properly built/compiled, we can create a Dockerfile. This file defines how to build the Docker image for the service by declaring the environment, building stages, and copying any binaries or assets needed to run the service to the Docker image filesystem. diff --git a/site/source/developer-docs/build-package-example/07_create-s9pk.rst b/site/source/developer-docs/build-package-example/07_create-s9pk.rst index c7ba471..c2faafe 100644 --- a/site/source/developer-docs/build-package-example/07_create-s9pk.rst +++ b/site/source/developer-docs/build-package-example/07_create-s9pk.rst @@ -1,8 +1,8 @@ .. _packaging-create-s9pk: -========================== -Step 7 - Package into s9pk -========================== +======================= +Step 7 - Format Package +======================= We now have all of the necessary components to package the service into the format needed for the OS. This format is a custom filetype with an extension of ``.s9pk``, short for Start9 Package. diff --git a/site/source/developer-docs/build-package-example/09_create-wrapper.rst b/site/source/developer-docs/build-package-example/09_create-wrapper.rst index 9335857..ef49062 100644 --- a/site/source/developer-docs/build-package-example/09_create-wrapper.rst +++ b/site/source/developer-docs/build-package-example/09_create-wrapper.rst @@ -1,8 +1,8 @@ .. _packaging-create-wrapper: -============================ -Step 9 - Create Wrapper Repo -============================ +======================= +Step 9 - Create Wrapper +======================= In order for the Start9 team to review your package for submission to the Start9 Marketplace, we ask that you create a wrapper repository for the project and its components. This repo should contain everything you need to build the service. diff --git a/site/source/developer-docs/build-package-example/10_install-package.rst b/site/source/developer-docs/build-package-example/10_install-package.rst index a02380f..6b2b944 100644 --- a/site/source/developer-docs/build-package-example/10_install-package.rst +++ b/site/source/developer-docs/build-package-example/10_install-package.rst @@ -19,10 +19,10 @@ Now that we have a process for iterating on producing a valid package for Embass 2. On an Embassy device, enter the ssh pubkey into your SSH settings: - #. Click on Embassy in the menu - #. Click on SSH under SETTINGS - #. Click on + Add new key - #. Paste pubkey from clipboard + 1. Click on Embassy in the menu + 2. Click on SSH under SETTINGS + 3. Click on + Add new key + 4. Paste pubkey from clipboard 3. Copy the ``hello-world.s9pk`` to the Embassy device: @@ -52,14 +52,14 @@ From here, you can play with viewing the results of your Manifest file settings, In order to verify your service is functioning as expected: -- Ensure your service is in "Running" state -- Make sure there are no apparent errors or warnings in the logs -- Ensure each UI component renders as expected: - - Instructions - - Config - - Properties - - Actions - - Interfaces - - Marketplace listing - - Donation -- Launch or use your service in the intended way and make sure all aspects function + - Ensure your service is in "Running" state + - Make sure there are no apparent errors or warnings in the logs + - Ensure each UI component renders as expected: + - Instructions + - Config + - Properties + - Actions + - Interfaces + - Marketplace listing + - Donation + - Launch or use your service in the intended way and make sure all aspects function diff --git a/site/source/developer-docs/build-package-example/resources.rst b/site/source/developer-docs/build-package-example/resources.rst index fd4c7a0..540b6a9 100644 --- a/site/source/developer-docs/build-package-example/resources.rst +++ b/site/source/developer-docs/build-package-example/resources.rst @@ -21,11 +21,11 @@ References Below are links to working examples of more advanced configurations for current Embassy services. They might serve as a starting point or reference during your development process: -- Detailed ``docker_entrypoint.sh`` - `Filebrowser `_ -- Optional dependencies - `BTCPay Server `__ -- Config spec - `BTCPay Server `__ -- Config rules - `BTC RPC Proxy `__ -- Multiple dependencies - `BTCPay Server `__ -- Actions - `BTCPay Server `__ -- Health checks - `BTCPay Server `__ -- Alerts - `BTCPay Server `__ + - Detailed ``docker_entrypoint.sh`` - `Filebrowser `_ + - Optional dependencies - `BTCPay Server `__ + - Config spec - `BTCPay Server `__ + - Config rules - `BTC RPC Proxy `__ + - Multiple dependencies - `BTCPay Server `__ + - Actions - `BTCPay Server `__ + - Health checks - `BTCPay Server `__ + - Alerts - `BTCPay Server `__ diff --git a/site/source/developer-docs/getting-started/environment-setup.rst b/site/source/developer-docs/getting-started/environment-setup.rst index 2b4b9b9..6b306fa 100644 --- a/site/source/developer-docs/getting-started/environment-setup.rst +++ b/site/source/developer-docs/getting-started/environment-setup.rst @@ -1,8 +1,8 @@ .. _environment-setup: -=========================== -Packaging Environment Setup -=========================== +================= +Environment Setup +================= To get started packaging a service for EmbassyOS, some basic knowledge of software development is required. Don't worry if you are inexperienced, we will provide enough context to get you started, and you can always reach out with questions. diff --git a/site/source/developer-docs/getting-started/index.rst b/site/source/developer-docs/getting-started/index.rst index 9d85237..0599037 100644 --- a/site/source/developer-docs/getting-started/index.rst +++ b/site/source/developer-docs/getting-started/index.rst @@ -37,7 +37,7 @@ Getting Started Overview :class: large-4 :anchor: Begin - Quickly get started with concise packaging steps + Quickly get started with concise steps .. topic-box:: :title: SDK diff --git a/site/source/developer-docs/getting-started/quick-start.rst b/site/source/developer-docs/getting-started/quick-start.rst index ed625ad..4939219 100644 --- a/site/source/developer-docs/getting-started/quick-start.rst +++ b/site/source/developer-docs/getting-started/quick-start.rst @@ -9,25 +9,25 @@ This guide outlines a checklist of steps to complete in order to package a servi Packaging --------- -1. Create or select project -2. Build project -3. Cross compile for armv8/aarch64 if necessary -4. Create Dockerfile and docker entrypoint file -5. Add build steps, compiled executables, assets, etc in Dockerfile and specify run command in docker entrypoint, handling signal exiting if the service does not already do this gracefully -6. Create Manifest file -7. Create instructions file -8. Create icon file -9. Add license -10. Package all components into s9pk using embassy-sdk -11. Verify package components using embassy-sdk -12. Create a wrapper repository on GitHub to host all package assets for review -13. (Optional) Add all package build steps to a Makefile for replicability + 1. Create or select project + 2. Build project + 3. Cross compile for armv8/aarch64 if necessary + 4. Create Dockerfile and docker entrypoint file + 5. Add build steps, compiled executables, assets, etc in Dockerfile and specify run command in docker entrypoint, handling signal exiting if the service does not already do this gracefully + 6. Create Manifest file + 7. Create instructions file + 8. Create icon file + 9. Add license + 10. Package all components into s9pk using embassy-sdk + 11. Verify package components using embassy-sdk + 12. Create a wrapper repository on GitHub to host all package assets for review + 13. (Optional) Add all package build steps to a Makefile for replicability Testing: -------- -1. Sideload ``.s9pk`` onto an Embassy -2. Install package using embassy-cli -3. Start package using embassy-cli, or in the UI -4. Check logs to see if errors -5. Ensure service is reachable/launchable + 1. Sideload ``.s9pk`` onto an Embassy + 2. Install package using embassy-cli + 3. Start package using embassy-cli, or in the UI + 4. Check logs to see if errors + 5. Ensure service is reachable/launchable diff --git a/site/source/developer-docs/getting-started/sdk.rst b/site/source/developer-docs/getting-started/sdk.rst index 0c34fa7..ee8ad58 100644 --- a/site/source/developer-docs/getting-started/sdk.rst +++ b/site/source/developer-docs/getting-started/sdk.rst @@ -49,10 +49,10 @@ embassy-sdk pack This command takes the necessary package components and assembles them into the `s9pk` file format needed to install a service on EmbassyOS. It expects the following files to exist: -- Manifest -- Instructions -- License -- Icon + - Manifest + - Instructions + - License + - Icon If this command fails, the error response will indicate which component is missing. @@ -61,11 +61,11 @@ embassy-sdk verify This command verifies aspects about the components assembled into the `s9pk`, such as: -- Ensures that all mounts are real volumes in the manifest -- Ensures all cert volumes point to real interfaces in the manifest -- Ensures all actions refer to real images in the manifest -- Ensures all images are tagged correctly in the manifest -- Ensures the icon is less than 100KB + - Ensures that all mounts are real volumes in the manifest + - Ensures all cert volumes point to real interfaces in the manifest + - Ensures all actions refer to real images in the manifest + - Ensures all images are tagged correctly in the manifest + - Ensures the icon is less than 100KB It should be run _after_ `embassy-sdk pack` in order to verify the validity of each component. @@ -83,12 +83,12 @@ This command contains several utilities for reading components once packaged int It contains the following subcommands, and requires the path to the `.s9pk` file as the last argument: -- docker-images -- hash -- icon -- instructions -- license -- manifest + - docker-images + - hash + - icon + - instructions + - license + - manifest For example: diff --git a/site/source/developer-docs/specification/properties.rst b/site/source/developer-docs/specification/properties.rst index 4645acc..23395b5 100644 --- a/site/source/developer-docs/specification/properties.rst +++ b/site/source/developer-docs/specification/properties.rst @@ -16,9 +16,18 @@ Due to the fact that config variables are only available when the service is run .. code:: typescript - :caption: Properties Type + interface Properties { + version: Enum, + data: Data, + } + + interface Data { + # The key here is an string that describes the property appropriately + : PropertiesString | PropertiesObject + } + interface PropertiesString { type: 'string' name: string @@ -38,7 +47,7 @@ Due to the fact that config variables are only available when the service is run Example ------- -A good example of the configurator producing the ``stats.yaml`` file can be found `here `_. +An example ``stats.yaml`` file generation can be found `here `__. .. role:: raw-html(raw) :format: html diff --git a/site/source/index.rst b/site/source/index.rst index 02cb923..c1198c0 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -113,7 +113,7 @@ .. This is for the side navigation display .. toctree:: - :maxdepth: 3 + :maxdepth: 4 :hidden: Purchase diff --git a/sphinx-scylladb-theme b/sphinx-scylladb-theme index 91c190c..8558b5f 160000 --- a/sphinx-scylladb-theme +++ b/sphinx-scylladb-theme @@ -1 +1 @@ -Subproject commit 91c190c7991738a632da94e88a88bcfdb093f6e3 +Subproject commit 8558b5f7704da1f4a0a52c40b390fc1ff7de290f