Merge pull request #134 from SunshineStream/add-sphinx-docs

Add sphinx docs

.github/workflows/CI.yml

@@ -150,7 +150,7 @@ jobs:
     strategy:
       fail-fast: true  # false to test all, true to fail entire job if any fail
       matrix:
-        distro: [ debian, ubuntu_18_04, ubuntu_20_04, ubuntu_21_04, ubuntu_21_10 ]
+        distro: [ debian, ubuntu_18_04, ubuntu_20_04, ubuntu_21_10 ]
         package: [ -p ]
         extension: [ deb ]
         include:  # package these differently

.github/workflows/clang.yml

@@ -9,10 +9,6 @@ jobs:
   lint:
     name: Clang Format Lint
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false  # false to test all, true to fail entire job if any fail
-      matrix:
-        inplace: [ true, false ]  # removed ubuntu_18_04 for now
 
     steps:
     - name: Checkout
@@ -25,10 +21,10 @@ jobs:
         extensions: 'cpp,h,m,mm'
         clangFormatVersion: 13
         style: file
-        inplace: ${{ matrix.inplace }}
+        inplace: false
 
     - name: Upload Artifacts
-      if: ${{ matrix.inplace == true }}
+      if: failure()
       uses: actions/upload-artifact@v3
       with:
         name: sunshine

.github/workflows/localize.yml

@@ -3,15 +3,16 @@ name: localize
 on:
   push:
     branches: [nightly]
-    paths:  # prevents workflow from running unless files in these directories change
-      - 'sunshine/**'  # only localizing files inside sunshine directory
+    paths:  # prevents workflow from running unless these files change
+      - 'sunshine/**'
+      - 'locale/sunshine.po'
   workflow_dispatch:
 
 jobs:
   localize:
     name: Update Localization
-    if: ${{ github.event.pull_request.merged }}
     runs-on: ubuntu-latest
+
     steps:
     - name: Checkout
       uses: actions/checkout@v3
@@ -37,9 +38,37 @@ jobs:
       run: |
         python ./scripts/_locale.py --extract
 
-    - name: GitHub Commit & Push  # push changes back into nightly
-      uses: actions-js/push@v1.3
+    - name: git diff
+      run: |
+        # print the git diff
+        git diff --exit-code locale/sunshine.po
+
+        # set the variable with minimal output
+        OUTPUT=$(git diff --exit-code --numstat locale/sunshine.po)
+        echo "git_diff=${OUTPUT}" >> $GITHUB_ENV
+
+    - name: git reset
+      if: ${{ env.git_diff != '1	1	locale/sunshine.po' }}  # only run if more than 1 line changed
+      run: |
+        git reset --hard
+
+    - name: Create/Update Pull Request
+      uses: peter-evans/create-pull-request@v4
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        branch: nightly
-        message: localization updated by localize workflow
+        add-paths: |
+          locale/*.po
+        token: ${{ secrets.GH_PAT }}  # must trigger PR tests
+        commit-message: New localization template
+        branch: localize/update
+        delete-branch: true
+        base: nightly
+        title: New Babel Updates
+        body: |
+          Update report
+          - Updated with *today's* date
+          - Auto-generated by [create-pull-request][1]
+
+          [1]: https://github.com/peter-evans/create-pull-request
+        labels: |
+          babel
+          l10n

.readthedocs.yaml

@@ -0,0 +1,26 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+  fail_on_warning: true
+
+# Using Sphinx, build docs in additional formats
+formats: all
+
+python:
+  install:
+    - requirements: ./scripts/requirements.txt
+  system_packages: true

DOCKER_README.md

@@ -0,0 +1,113 @@
+# Docker
+
+## Using docker run
+Create and run the container (substitute your `<values>`):
+
+```bash
+docker run -d \
+  --name=sunshine \
+  --restart=unless-stopped
+  -v <path to data>:/config \
+  -e PUID=<uid> \
+  -e PGID=<gid> \
+  -e TZ=<timezone> \
+  -p 47990:47990 \
+  -p 47984:47984 \
+  -p 47989:47989 \
+  -p 48010:48010 \
+  -p 47998:47998 \
+  -p 47999:47999 \
+  -p 48000:48000 \
+  -p 48002:48002 \
+  -p 48010:48010 \
+  sunshinestream/sunshine
+```
+
+To update the container it must be removed and recreated:
+
+```bash
+# Stop the container
+docker stop sunshine
+# Remove the container
+docker rm sunshine
+# Pull the latest update
+docker pull sunshinestream/sunshine
+# Run the container with the same parameters as before
+docker run -d ...
+```
+
+## Using docker-compose
+
+Create a `docker-compose.yml` file with the following contents (substitute your `<values>`):
+
+```yaml
+version: '3'
+services:
+  sunshine:
+    image: sunshinestream/sunshine
+    container_name: sunshine
+    restart: unless-stopped
+    volumes:
+    - <path to data>:/config
+    environment:
+    - PUID=<uid>
+    - PGID=<gid>
+    - TZ=<timezone>
+    ports:
+    - "47990:47990"
+    - "47984:47984"
+    - "47989:47989"
+    - "48010:48010"
+    - "47998:47998"
+    - "47999:47999"
+    - "48000:48000"
+    - "48002:48002"
+    - "48010:48010"
+```
+
+Create and start the container (run the command from the same folder as your `docker-compose.yml` file):
+
+```bash
+docker-compose up -d
+```
+
+To update the container:
+```bash
+# Pull the latest update
+docker-compose pull
+# Update and restart the container
+docker-compose up -d
+```
+
+## Parameters
+You must substitute the `<values>` with your own settings.
+
+Parameters are split into two halves separated by a colon. The left side represents the host and the right side the
+container.
+
+**Example:** `-p external:internal` - This shows the port mapping from internal to external of the container.
+Therefore `-p 47990:47990` would expose port `47990` from inside the container to be accessible from the host's IP on
+port `47990` (e.g. `http://<host_ip>:47990`). The internal port must be `47990`, but the external port may be changed
+(e.g. `-p 8080:47990`).
+
+
+| Parameter                   | Function             | Example Value       | Required |
+| --------------------------- | -------------------- | ------------------- | -------- |
+| `-p <port>:47990`           | Web UI Port          | `47990`             | True     |
+| `-v <path to data>:/config` | Volume mapping       | `/home/sunshine`    | True     |
+| `-e PUID=<uid>`             | User ID              | `1001`              | False    |
+| `-e PGID=<gid>`             | Group ID             | `1001`              | False    |
+| `-e TZ=<timezone>`          | Lookup TZ value [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | `America/New_York` | True     |
+
+### User / Group Identifiers:
+
+When using data volumes (-v flags) permissions issues can arise between the host OS and the container. To avoid this
+issue you can specify the user PUID and group PGID. Ensure the data volume directory on the host is owned by the same
+user you specify.
+
+In this instance `PUID=1001` and `PGID=1001`. To find yours use id user as below:
+
+```bash
+$ id dockeruser
+uid=1001(dockeruser) gid=1001(dockergroup) groups=1001(dockergroup)
+```