Formatting edits for new theme

source/dev-docs/dev-faq/faq-contributing.rst

@@ -1,8 +1,8 @@
 .. _faq-contributing:
 
-************
+============
 Contributing
-************
+============
 
 We ❤️ contributions!
 
@@ -12,7 +12,6 @@ Do I need to be a professional developer or have coding experience to contribute
 ---------------------------------------------------------------------------------
 Absolutely not!  Contributions can be as simple as finding a typo in our docs, making a suggestion on GitHub, creating educational or promotional content, and the list goes on!  Everyone that wants to contribute can do so in some unique way.  Please don't hesitate to ***CONTACT LINK*** us for ideas if you're not sure where to begin.
 
-
 Expound the following into FAQs move to other dev-faq section if necessary:
 ---------------------------------------------------------------------------
 

source/dev-docs/dev-faq/faq-service-packaging.rst

@@ -1,8 +1,8 @@
 .. _faq-service-packaging:
 
-*********************
+=====================
 Service Packaging FAQ
-*********************
+=====================
 
 Do I need programming experience to package a service for EmbassyOS?
 --------------------------------------------------------------------

source/dev-docs/dev-faq/index.rst

@@ -1,8 +1,10 @@
-*************
-Developer FAQ
-*************
+.. _dev-faq:
 
-An overview of EmbassyOS general capabilities.
+=============
+Developer FAQ
+=============
+
+Frequently Asked Questions by and for developers.  If you have a suggestion, please use the Github link at the top of the page.
 
 .. toctree::
   :maxdepth: 2

source/dev-docs/packaging-example.rst

@@ -1,18 +1,18 @@
 .. _packaging-example:
 
-*************************
+=========================
 Service Packaging Example
-*************************
+=========================
 
 A rough walkthrough of how to package a service using our example `hello-world-wrapper <https://github.com/Start9Labs/hello-world-wrapper>`_.
 
 Welcome!  The following guide will provide the prerequisites, introduce a brief overview of the packaging process, use an example demonstrating how to package a service, and finally describe the submission process.  This essentially describes how you can take an existing app (or one you have written yourself), and wrap it up such that it can be added to an EmbassyOS Marketplace!
 
 Pre-requisites
-==============
+--------------
 
 EmbassyOS (EOS)
----------------
+...............
 
 It is **HIGHLY RECOMMENDED** to have a copy of EmbassyOS for testing your packaged service.
 
@@ -22,7 +22,7 @@ There are 3 options for this:
     #. :ref:`Purchse <purchasing>` a device or copy of the OS
 
 Development Environment
------------------------
+.......................
 
 Once you have EOS installed, you'll want to set up your development system with the necessary software.
 
@@ -38,10 +38,10 @@ The following are recommended:
     #. rust-musl-cross (***PLACEHOLDER FOR NEW MUSL-CROSS REPO***) (For cross compiling Rust to Alpine, not needed otherwise)
 
 Overview
-========
+--------
 
 Components
-----------
+..........
 
 Simply, the package is made up of the following parts:
     1. Image - Each service is running in a Docker image.  Best results will come from an arm based linux; [Alpine](https://www.alpinelinux.org/) is highly recommended.
@@ -54,7 +54,7 @@ Simply, the package is made up of the following parts:
 Check :ref:`here <service_package_overview>` for a detailed overview of package components.
 
 Service Wrapper Repo and Submodules
------------------------------------
+...................................
 
 See :ref:`here <service_wrapper>` for how to structure your service wrapper's git repository.
 
@@ -67,12 +67,12 @@ Simply run:
   git submodule add <link_to_source_project>
 
 Example - Hello World
-=====================
+---------------------
 
 Okay, let's actually package a service!  For this example, we're going to use an example service `Hello World <https://github.com/Start9Labs/hello-world>`_.  This repository can also be used as a template to quickly get started with your service.  This will give a good overview of service packaging, but obviously your app will be different.  This will assume a Linux development environment with all the recommended dependencies listed above.  To get started quickly, we'll use Start9's wrapper template.
 
 Clone the Template Repo and Edit the Manifest
----------------------------------------------
+.............................................
 
 1. Clone and rename the repo (or alternatively, use the template generation button found on the github `repo <https://github.com/Start9Labs/hello-world-wrapper>`_)
 
@@ -86,7 +86,7 @@ Clone the Template Repo and Edit the Manifest
 3. Edit the ``manifest`` file.  This must be in ``.json``, ``.toml``, or ``.yaml`` format and in ``kebab-case`` style.  You can see descriptions of each key (and some notes) in our 'Hello World' example ``manifest.yaml`` below:
 
 Manifest example
-----------------
+................
 
 .. code-block:: yaml
 
@@ -247,7 +247,7 @@ Note the ``dependencies`` and ``volumes`` sections, which may access another ser
 For details on all the different possible dependency, type, and subtype definitions available for the ``manifest`` file, please see :ref:`here <service_manifest>`.
 
 Edit the Dockerfile and Entrypoint
-----------------------------------
+..................................
 
 Next, it's time to edit the ``Dockerfile``.  This defines how to build the image for the package by declaring the environment, building stages, and mounting the package to the volume specified in the ``manifest``.
 
@@ -318,7 +318,7 @@ Next, it's time to edit the ``Dockerfile``.  This defines how to build the image
 For a more detailed ``docker_entrypoint.sh``, please check out the `filebrowser-wrapper <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/docker_entrypoint.sh>`_.  Additional details on the ``Dockerfile`` and ``docker_entrypoint`` can be found `here <https://docs.start9.com/contributing/services/docker.html>`_.
 
 Makefile (Optional)
--------------------
+...................
 
 Here, we will create a ``Makefile``, which is optional, but recommended as it outlines the build and streamlines additional developer contributions.  Alternatively, you could use any other build orchestration tool, such as ``nix``, ``bash``, ``python``, ``perl``, ``ruby``, etc instead of ``make``.
 
@@ -370,7 +370,7 @@ Our example ``Makefile`` is agin fairly simple for Hello World.  Let's take a lo
 For more details on creating a ``Makefile`` for your project, please check :ref:`here <service_makefile>`.
 
 Service Config Specification and Rules
---------------------------------------
+......................................
 
 Most self-hosted packages require a configuration.  With EmbassyOS, these config options are provided to the user in a friendly GUI, and invalid configs are not permitted.  This allows the user to manage their software without a lot of technical skill, and minimal risk of borking their software.  Two files are created in this process:
 
@@ -482,14 +482,14 @@ In our example, there is *no need* for a ``config_rules`` file.  This is because
 Here we see that a Maximum Channel Size **MUST** be one of 3 possible options in order to be a valid config.
 
 Properties
-----------
+..........
 
 Next we need to create the Properties section for our package, to display any relevant info.  The result of this step is a ``stats.yaml`` file, which is only populated at runtime.  These commands will be issued in the ``docker_entrypoint`` file (or ``configurator``, if you are using one).
 
 ***STATS.YAML IS APPARENTLY BEING DEPRECATED, THIS SECTION NEEDS COMMENT***
 
 Instructions
-------------
+............
 
 Instructions are the basic directions or any particular details that you would like to convey to the user to help get them on their way.  Each wrapper repo should contain a ``docs`` directory which can include anything you'd like, but specifically if you include an ``instructions.md`` file, formatted in Markdown language, it will be displayed simply for the user as shown below.
 
@@ -498,12 +498,12 @@ Instructions are the basic directions or any particular details that you would l
 You can find the ``instructions.md`` file for Embassy Pages `here <https://github.com/Start9Labs/embassy-pages-wrapper/tree/master/docs>`_ if you are interested.
 
 Backups
--------
+.......
 
 Everything in the root folder of the mounted system directory will be stored in an EOS backup.  If you want to ignore any particular files for backup, you can create a ``.backupignore`` file and add the relative paths of any directories you would like ignored.
 
 Submission Process
-------------------
+..................
 
 When you have built and tested your project for EmbassyOS, please send Start9 a submission with the project repository to dev@start9labs.com. After being reviewed for security and compatibility, the service will be deployed to the marketplace and available for all EmbassyOS users to download.
 

source/dev-docs/service-packaging/backups.rst

@@ -1,8 +1,8 @@
 .. _service_backups:
 
-***************
+===============
 Service Backups
-***************
+===============
 
 Everything within the root of the mounted volume directory will be stored in an EmbassyOS backup. This includes the config (config.yaml) and properties (stats.yaml) files, as well as any other persisted data within the volume directory. 
 
@@ -12,7 +12,7 @@ In this case, create a `.backupignore` file. This file contains a list of relati
 
 
 Example
-=======
+-------
 
 The `btcpayserver wrapper <https://github.com/Start9Labs/btcpayserver-wrapper/blob/master/configurator/src/templates/.backupignore.templates>`_ demonstrates a good use of a backupignore template.
 

source/dev-docs/service-packaging/config.rst

@@ -1,11 +1,11 @@
 .. _service_config:
 
-****************************
+============================
 Service Config Specification
-****************************
+============================
 
 Overview
-========
+--------
 
 Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's configuration will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
 
@@ -24,10 +24,10 @@ For example, if the user chooses config option A, then config option B must be b
 .. _config_spec:
 
 Config Spec
-===========
+-----------
 
 Overview
---------
+........
 
 .. figure:: /_static/images/service/bitcoin_config.png
   :width: 80%
@@ -49,7 +49,7 @@ The neat part about this file is that each ValueSpec type gets translated into a
 Another advantage is the ability to define default values. These values automatically get populated if the user selects the ``Default`` option when setting up a service in ``Needs Config`` state. This is super convenient for users who want to get up and running quickly.
 
 Types
------
+.....
 
 ConfigSpec Type:
 
@@ -60,7 +60,7 @@ ConfigSpec Type:
     ValueSpec Type: Boolean | Enum | List | Number | Object | String | Union | Pointer (see below for details)
 
 Implementation Guide
---------------------
+....................
 
 The following section contains implementation specifications for the ``config_spec.yaml`` file.
 
@@ -506,7 +506,7 @@ Example:
 .. _config_rules:
 
 Config Rules
-============
+------------
 
 This file defines the configuration rules, or the rule-set that defines dependencies between config variables. In practice, config rules are for auto-configuring self dependencies. Self dependencies are internal dependencies of a service, such as if the setting of one config variable informs the option of another setting. These "dependencies" are configured as rules. 
 

source/dev-docs/service-packaging/docker.rst

@@ -1,11 +1,11 @@
 .. _service_docker:
 
-******************
+==================
 Service Dockerfile
-******************
+==================
 
 Dockerfile
-==========
+----------
 
 This purpose of the Dockerfile is to define how to build the image for the service. It declares the environment and building stages.
 The Dockerfile is responsible for mounting the service application to whatever volume the manifest specifies, typically ``/root/.<service-id>``.
@@ -23,14 +23,14 @@ For instance:
 We recommended using ``alpine`` since it produces the smallest image. We try to keep the image under 100MB when possible.
 
 Entry-point
-===========
+-----------
 
 The ``docker_entrypoint.sh`` defines what to do when the service application starts.
 
 It consists of a bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. The only required feature of this file is to execute the run commands for EmbassyOS.
 
 Example
-=======
+-------
 
 The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Dockerfile>`_ features a well defined Dockerfile, for example.
 

source/dev-docs/service-packaging/index.rst

@@ -1,6 +1,8 @@
-*******************************
+.. _service-packaging-spec:
+
+===============================
 Service Packaging Specification
-*******************************
+===============================
 
 Welcome! If you are here, you are interested in becoming part of the mission to change the future of personal computing. This guide will take you through the process of packaging a service for EmbassyOS, a novel, self-hosted, sovereign computing platform.
 

source/dev-docs/service-packaging/instructions.rst

@@ -1,8 +1,8 @@
 .. _service_instructions:
 
-************************************
+====================================
 Service Instructions & Documentation
-************************************
+====================================
 
 Within each wrapper repository should exist a ``docs`` directory. This folder should include any pertinent documentation, instructions, external integrations, or other details about the service that users or developers might find relevant.
 
@@ -13,7 +13,7 @@ If an ``instructions.md`` file is included, this markdown formatted file will be
   :alt: Bitcoin Instructions
 
 Example
-=======
+-------
 
 The `bitcoind wrapper <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs>`_ demonstrates a good use of instructions and external integrations.
 

source/dev-docs/service-packaging/makefile.rst

@@ -1,8 +1,8 @@
 .. _service_makefile:
 
-****************
+================
 Service Makefile
-****************
+================
 
 .. note::
 
@@ -20,7 +20,7 @@ This purpose of this file is to:
 - Package ``config_rules.yaml``, ``config_spec.yaml``, ``manifest.yaml``, and ``image.tar`` into an ``.s9pk`` extension by invoking ``appmgr``.
 
 Example
-=======
+-------
 
 The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Makefile>`_ features a well defined Makefile, for example.
 

source/dev-docs/service-packaging/manifest.rst

@@ -1,11 +1,11 @@
 .. _service_manifest:
 
-****************
+================
 Service Manifest
-****************
+================
 
 Overview
-========
+--------
 
 This file describes the service and it's requirements. It is used to:
 
@@ -22,13 +22,14 @@ There is nothing you need to do as a developer to set up Tor for running a servi
 The manifest is also responsible for outlining service :ref:`dependencies <dependencies>`. By defining rules using the :ref:`EmbassyOS DSL specification <config_rules>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. EmbassyOS presents this information in a polished install/uninstall/update wizard, so there's no need for editing configuration files or jumping into the command line. For you as a developer, this simply means populating this key in the manifest!
 
 Formatting
-==========
+----------
 
 - Serialization language:``.yaml``
 - Case style: ``kebab-case``
 
 Type definitions
-================
+----------------
+
 Below are the types and sub-type definitions, with necessary elaborations. Any item that contains ``Option<>`` is an optional field.
 
 .. code:: yaml
@@ -84,7 +85,7 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
 .. _dependencies:
 
 Dependencies
-============
+------------
 
 Many services depend on other libraries and services on EmbassyOS (such as Bitcoin), sometimes even a particular version of those services, which need to be specified by the developers so that EmbassyOS can handle installing these dependencies under the hood.
 
@@ -121,7 +122,7 @@ The service ``btc-rpc-proxy`` is a dependency of the service ``c-lightning``. ``
     Dependency config rules are processed in order.
 
 Type definitions
-----------------
+................
 
 Types for ``manifest.yaml`` fields:
 
@@ -174,7 +175,7 @@ Types for ``manifest.yaml`` fields:
 :raw-html:`<br />`
 
 Examples
---------
+........
 
 Actual ``manifest.yaml`` files for existing services:
 

source/dev-docs/service-packaging/overview.rst

@@ -1,20 +1,20 @@
 .. _service_package_overview:
 
-************************
+========================
 Service Package Overview
-************************
+========================
 
 There are several main components that comprise a service package for EmbassyOS. This overview will introduce them and following sections will dive into technical specifics.
 
 First, let's get your system setup with the necessary software dependencies.
 
 Environment Setup
-=================
+-----------------
 
 At minimum, ``docker``, ``docker-buildx``, and ``appmgr`` are required. The rest of the recommendations serve to optimize the build process.
 
 Recommended Dependencies
-------------------------
+........................
 
     `docker <https://docs.docker.com/get-docker>`_
 
@@ -31,10 +31,10 @@ Recommended Dependencies
     `musl <https://github.com/Start9Labs/rust-musl-cross>`_
 
 Package Components
-==================
+------------------
 
 Image
------
+.....
 
 Each service boils down to a Docker image. We're not going to dive into Docker specifics in this guide, since there exists tons of `resources <https://docs.docker.com/>`_ for developing with this containerization tool.
 
@@ -43,7 +43,8 @@ Because the service ultimately runs on a Raspberry Pi, the created Docker image
 The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features.
 
 Volume
-------
+......
+
 Each service application gets a volume allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates.
 
 The volume directory (for seeding data into the volume) is typically: ``/root/volumes/<service-id>``.
@@ -52,7 +53,7 @@ The volume directory (for seeding data into the volume) is typically: ``/root/vo
     Any files that are in the image at the volume path will be overwritten when a backup restore occurs.
 
 Dependencies
-------------
+............
 
 When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this feat.
 
@@ -65,7 +66,7 @@ The key to making the system work is a new, domain-specific-language (DSL) and s
 This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <dependencies>` key in the service manifest.
 
 Manifest
---------
+........
 
 This file describes the service and its requirements. It is used to:
 
@@ -80,21 +81,21 @@ For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/bl
 There is nothing you need to do as a developer to enable the service to run over Tor. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated and an Nginx server configured (if a client application) when the service is installed. Just define which version of Tor your service needs in this manifest file!
 
 Config
-------
+......
 
 Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's :ref:`configuration <service_config>` will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
 
 With EmbassyOS, this means a service wrappers' configuration requires a particular format and rule structure to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and configuration dependencies.
 
 .s9pk Bundle
-------------
+............
 
 The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_. Each new version release should include the updated version of these files re-bundled into a new binary. This is the file that will be downloaded from the marketplace. Upon user initiation, EmbassyOS then un-packages and installs the service.
 
 Hello World Example
--------------------
+...................
 
-For reference, the `Hello world <https://github.com/Start9Labs/hello-world-wrapper>`_ repository should be used as an example. A project template can be cloned using the "Use this template" button in GitHub.
+For reference, the `Hello world <https://github.com/Start9Labs/hello-world-wrapper>`_ repository should be used as an example. A project template can be cloned using the "Use this template" button in GitHub.  For a detailed walkthrough of this example, please see the :ref:`Packaging Example<packaging-example>`.
 
 
 .. role:: raw-html(raw)

source/dev-docs/service-packaging/properties.rst

@@ -1,8 +1,8 @@
 .. _service_properties:
 
-******************
+==================
 Service Properties
-******************
+==================
 
 The output of this step is a file titled ``stats.yaml``. This file contains a mapping of the values that will be displayed in the ``Properties`` section in a service's menu.
 
@@ -15,7 +15,7 @@ The output of this step is a file titled ``stats.yaml``. This file contains a ma
 Due to the fact that config variables are only available when the service is running, this file can only be populated at runtime. In services Start9 has wrapped or created, we typically handle this in ``configurator/src/main.rs``. This file is essentially a script that acquires the necessary values at runtime from config (eg. ``/root/.lnd/start9/config.yaml``), and dynamically populating them to the ``stats.yaml`` file, marking each value with the appropriate keys for UI display (ie. masked or copyable). Running the configurator is typically included in the ``docker_entrypoint.sh`` file.
 
 Example
-=======
+-------
 
 A good example of the configurator producing the ``stats.yaml`` file can be found `here <https://github.com/Start9Labs/lnd-wrapper/blob/master/configurator/src/main.rs>`_.
 

source/dev-docs/service-packaging/wrapper.rst

@@ -1,8 +1,8 @@
 .. _service_wrapper:
 
-***************
+===============
 Service Wrapper
-***************
+===============
 
 Each service is bound with a wrapper repository, which contains everything you need to build a service.
 
@@ -17,7 +17,7 @@ The purpose of this repo is:
 - symlink of ``instructions.md`` from ``docs`` directory to wrapper repo root, if included
 
 File Structure
-==============
+--------------
 
 The project structure should be used as a model:
 
@@ -35,7 +35,7 @@ The project structure should be used as a model:
     └── manifest.yaml
 
 Submodule
-==========
+---------
 
 `Git submodules <https://www.git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allow use of another project while in the working project directory. Setting up this feature enables linking of the source service repository so that its context is available.