jyapayne/Sunshine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial version of sphinx documentation and...

Browse source 
- remove ubuntu 21.04 from CI (end of life)
- adjust matrix strategy for clang.yml
- Use lessons learned from RetroArcher on localize.yml, crowdin.yml, and locale.py
- Add end of life comments to Dockerfiles
- Adjust dependency order in Dockerfiles
This commit is contained in:
ReenigneArcher 2022-04-18 14:53:28 -04:00
commit 536df759ae
35 changed files with 2350 additions and 342 deletions
Download patch file Download diff file Expand all files Collapse all files

1087
docs/source/about/advanced_usage.rst Normal file
View file

File diff suppressed because it is too large Load diff

5
docs/source/about/docker.rst Normal file
View file

@ -0,0 +1,5 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/DOCKER_README.md
.. Todo:: This is a planned feature. Currently no Dockerfile or image exists for Sunshine.
.. mdinclude:: ../../../DOCKER_README.md

84
docs/source/about/installation.rst Normal file
View file

@ -0,0 +1,84 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/installation.rst
Installation
============
The recommended method for running Sunshine is to use the `binaries`_ bundled with the `latest release`_.
Binaries
--------
Binaries of Sunshine are created for each release. They are available for Linux, and Windows.
Binaries can be found in the `latest release`_.
.. Todo:: Create binary package(s) for MacOS. See `here <https://github.com/SunshineStream/Sunshine/issues/61>`_.
.. Tip:: Some third party packages also exist. See
:ref:`Third Party Packages <about/third_party_packages:third party packages>`.
Docker
------
.. Todo:: Docker images of Sunshine are planned to be included in the future.
They will be available on `Dockerhub.io`_ and `ghcr.io`_.
Linux
-----
AppImage
^^^^^^^^
.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/pkg:appimage?logo=github&style=for-the-badge'
:alt: GitHub issues by-label
#. Download and extract `sunshine-appimage.zip`
Debian Packages
^^^^^^^^^^^^^^^
.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:linux:debian?logo=github&style=for-the-badge'
:alt: GitHub issues by-label
#. Download the corresponding `.deb` file, e.g. ``sunshine-ubuntu_20_04.deb``
#. ``sudo apt install -f <downloaded deb file>``, e.g. ``sudo apt install -f ./sunshine-ubuntu_20_04.deb``
Red Hat Packages
^^^^^^^^^^^^^^^^
.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:linux:fedora?logo=github&style=for-the-badge'
:alt: GitHub issues by-label
#. Download the corresponding `.rpm` file, e.g. ``sunshine-fedora_35.rpm``
#. ``sudo rpm -i <downloaded rpm file>``, e.g. ``sudo rpm -i ./sunshine-fedora_35.rpm``
.. Note:: If this is the first time installing.
.. code-block:: bash
sudo usermod -a -G input $USER
sudo reboot now
.. Tip:: Optionally, run Sunshine in the background.
.. code-block:: bash
systemctl --user start sunshine
MacOS
-----
.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:macos?logo=github&style=for-the-badge'
:alt: GitHub issues by-label
#. Install `MacPorts <https://www.macports.org>`_
#. Download the `Portfile <https://github.com/SunshineStream/Sunshine/blob/master/Portfile>`_ from this repository to
``/tmp``
#. In a terminal run ``cd /tmp && sudo port install``
#. The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone.
Windows
-------
.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:windows:10?logo=github&style=for-the-badge'
:alt: GitHub issues by-label
.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:windows:11?logo=github&style=for-the-badge'
:alt: GitHub issues by-label
#. Download and extract ``sunshine-windows.zip``
.. _latest release: https://github.com/SunshineStream/Sunshine/releases/latest
.. _Dockerhub.io: https://hub.docker.com/repository/docker/sunshinestream/sunshine
.. _ghcr.io: https://github.com/orgs/SunshineStream/packages?repo_name=sunshine

1
docs/source/about/overview.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../README.rst

65
docs/source/about/third_party_packages.rst Normal file
View file

@ -0,0 +1,65 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/third_party_packages.rst
Third Party Packages
====================
.. Warning:: These packages are not maintained by SunshineStream. Use at your own risk.
AUR (Arch Linux User Repository)
--------------------------------
.. image:: https://img.shields.io/aur/version/sunshine?style=for-the-badge&logo=archlinux
:alt: AUR version
.. image:: https://img.shields.io/aur/last-modified/sunshine?style=for-the-badge&logo=archlinux
:alt: AUR last modified
.. image:: https://img.shields.io/aur/votes/sunshine?style=for-the-badge&logo=archlinux
:alt: AUR votes
.. image:: https://img.shields.io/aur/maintainer/sunshine?style=for-the-badge&logo=archlinux
:alt: AUR maintainer
.. image:: https://img.shields.io/static/v1?label=maintainer&message=hadogenes&color=blue&style=for-the-badge&logo=github
:alt: GitHub Maintainer
:target: https://github.com/hadogenes
Chocolatey
----------
.. image:: https://img.shields.io/chocolatey/v/Sunshine?style=for-the-badge&logo=chocolatey
:alt: Chocolatey Version
.. image:: https://img.shields.io/chocolatey/dt/sunshine?style=for-the-badge&logo=chocolatey
:alt: Chocolatey
.. image:: https://img.shields.io/static/v1?label=maintainer&message=AeliusSaionji&color=blue&style=for-the-badge&logo=github
:alt: GitHub Maintainer
:target: https://github.com/AeliusSaionji
Scoop
-----
.. image:: https://img.shields.io/scoop/v/sunshine?bucket=extras&style=for-the-badge
:alt: Scoop Version (extras bucket)
.. image:: https://img.shields.io/static/v1?label=maintainer&message=sitiom&color=blue&style=for-the-badge&logo=github
:alt: GitHub Maintainer
:target: https://github.com/sitiom
Legacy GitHub Repo
------------------
.. image:: https://img.shields.io/github/last-commit/loki-47-6F-64/sunshine?style=for-the-badge&logo=github
:alt: GitHub last commit
.. image:: https://img.shields.io/github/release-date/loki-47-6F-64/sunshine?style=for-the-badge&logo=github
:alt: GitHub Release Date
.. image:: https://img.shields.io/github/downloads/loki-47-6F-64/sunshine/total?style=for-the-badge&logo=github
:alt: GitHub Releases
.. image:: https://img.shields.io/static/v1?label=maintainer&message=loki-47-6F-64&color=blue&style=for-the-badge&logo=github
:alt: GitHub Maintainer
:target: https://github.com/loki-47-6F-64

163
docs/source/about/usage.rst Normal file
View file

@ -0,0 +1,163 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/usage.rst
Usage
=====
#. See the `setup`_ section for your specific OS.
#. Run ``sunshine <directory of conf file>/sunshine.conf``.
.. Note:: The configuration file specified will be created if it doesn't exist.
.. Tip:: If using the Linux AppImage, replace ``sunshine`` with ``./sunshine.AppImage``
#. Configure Sunshine in the web ui
The web ui is available on `https://localhost:47990 <https://localhost:47990>`_ by default. You may replace
`localhost` with your internal ip address.
.. Tip:: Ignore any warning given by your browser about "insecure website".
.. Caution:: If running for the first time, make sure to note the username and password Sunshine showed to you,
since you cannot get back later!
Add games and applications.
This can be configured in the web ui.
.. Note:: Additionally, apps can be configured manually. `assets/apps_<os>.json` is an example of a list of
applications that are started just before running a stream.
.. Note:: Application list is not fully supported on MacOS
#. In Moonlight, you may need to add the PC manually.
#. When Moonlight request you insert the correct pin on sunshine:
- Login to the web ui
- Go to "PIN" in the Header
- Type in your PIN and press Enter, you should get a Success Message
- In Moonlight, select one of the Applications listed
Network
-------
Sunshine will be available on port 47990 by default.
.. Warning:: Do not expose port 47990, or the web ui, to the internet!
Arguments
---------
To get a list of available arguments run the following:
.. code-block:: bash
sunshine --help
Setup
-----
Linux
^^^^^
Sunshine needs access to `uinput` to create mouse and gamepad events.
Add user to group `input`.
.. code-block:: bash
usermod -a -G input $USER
Create `udev` rules.
.. code-block:: bash
nano /etc/udev/rules.d/85-sunshine-input.rules
Input the following contents:
``KERNEL=="uinput", GROUP="input", MODE="0660"``
Save the file and exit:
#. ``CTRL+X`` to start exit.
#. ``Y`` to save modifications.
Configure autostart service
`path/to/build/dir/sunshine.service` is used to start sunshine in the background. To use it, do the following:
#. Copy it to the users systemd: ``cp sunshine.service ~/.config/systemd/user/``
#. Starting
- One time: ``systemctl --user start sunshine``
- Always on boot: ``systemctl --user enable sunshine``
Additional Setup for KMS
.. Note:: ``cap_sys_admin`` may as well be root, except you don't need to be root to run it.
It is necessary to allow Sunshine to use KMS: ``sudo setcap cap_sys_admin+p sunshine``
MacOS
^^^^^
Sunshine can only access microphones on macOS due to system limitations. To stream system audio use
`Soundflower <https://github.com/mattingalls/Soundflower>`_ or
`BlackHole <https://github.com/ExistentialAudio/BlackHole>`_ and
select their sink as audio device in `sunshine.conf`.
.. Note:: Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key.
.. Caution:: Gamepads are not supported.
Windows
^^^^^^^
For gamepad support, install `ViGEmBus <https://github.com/ViGEm/ViGEmBus/releases/latest>`_
Shortcuts
---------
All shortcuts start with CTRL + ALT + SHIFT, just like Moonlight
- ``CTRL + ALT + SHIFT + N`` - Hide/Unhide the cursor (This may be useful for Remote Desktop Mode for Moonlight)
- ``CTRL + ALT + SHIFT + F1/F13`` - Switch to different monitor for Streaming
Application List
----------------
- You can use Environment variables in place of values
- ``$(HOME)` will be replaced by the value of ``$HOME``
- ``$$`` will be replaced by ``$``, e.g. ``$$(HOME)`` will be replaced by ``$(HOME)``
- ``env`` - Adds or overwrites Environment variables for the commands/applications run by Sunshine
- ``"Variable name":"Variable value"``
- ``apps`` - The list of applications
- Example application:
.. code-block:: json
{
"name":"An App",
"cmd":"command to open app",
"prep-cmd":[
{
"do":"some-command",
"undo":"undo-that-command"
}
],
"detached":[
"some-command",
"another-command"
]
}
- ``name`` - The name of the application/game
- ``output`` - The file where the output of the command is stored
- ``detached`` - A list of commands to be run and forgotten about
- ``prep-cmd`` - A list of commands to be run before/after the application
- If any of the prep-commands fail, starting the application is aborted
- ``do`` - Run before the application
- If it fails, all ``undo`` commands of the previously succeeded ``do`` commands are run
- ``undo`` - Run after the application has terminated
- This should not fail considering it is supposed to undo the ``do`` commands
- If it fails, Sunshine is terminated
- ``cmd`` - The main application
- If not specified, a process is started that sleeps indefinitely
Considerations
--------------
- When an application is started, if there is an application already running, it will be terminated.
- When the application has been shutdown, the stream shuts down as well.
- In addition to the apps listed, one app "Desktop" is hardcoded into Sunshine. It does not start an application,
instead it simply starts a stream.

31
docs/source/building/build.rst Normal file
View file

@ -0,0 +1,31 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/build.rst
Build
=====
Sunshine binaries are built using `CMake <https://cmake.org/>`_. Cross compilation is not
supported. That means the binaries must be built on the target operating system and architecture.
Building Locally
----------------
Clone
^^^^^
Ensure `git <https://git-scm.com/>`_ is installed and run the following:
.. code-block:: bash
git clone https://github.com/sunshinestream/sunshine.git --recurse-submodules
cd sunshine && mkdir build && cd build
Build
^^^^^
See the section specific to your OS.
Remote Build
------------
It may be beneficial to build remotely in some cases. This will enable easier building on different operating systems.
#. Fork the project
#. Activate workflows
#. Trigger the `CI` workflow manually
#. Download the artifacts/binaries from the workflow run summary

241
docs/source/building/linux.rst Normal file
View file

@ -0,0 +1,241 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/linux.rst
Linux
=====
Requirements
------------
.. Warning:: Installing these dependencies may break your distribution. It is recommended to build in a virtual machine
or to use the Dockerfile builds located in the `./scripts` directory.
Debian Bullseye
"""""""""""""""
End of Life: TBD
Install Requirements
.. code-block:: bash
sudo apt update && sudo apt install \
build-essential \
cmake \
git \
libavdevice-dev \
libboost-filesystem-dev \
libboost-log-dev \
libboost-thread-dev \
libcap-dev \ # KMS
libdrm-dev \ # KMS
libevdev-dev \
libpulse-dev \
libopus-dev \
libssl-dev \
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
nvidia-cuda-dev \ # Cuda, NvFBC
nvidia-cuda-toolkit \ # Cuda, NvFBC
Fedora 35
"""""""""
End of Life: TBD
Install Repositories
.. code-block:: bash
sudo dnf update && \
sudo dnf group install "Development Tools" && \
sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
Install Requirements
.. code-block:: bash
sudo dnf install \
boost-devel \
boost-static.x86_64 \
cmake \
ffmpeg-devel \
gcc-c++ \
libevdev-devel \
libX11-devel \ # X11
libxcb-devel \ # X11
libXcursor-devel \ # X11
libXfixes-devel \ # X11
libXinerama-devel \ # X11
libXi-devel \ # X11
libXrandr-devel \ # X11
libXtst-devel \ # X11
mesa-libGL-devel \
openssl-devel \
opus-devel \
pulseaudio-libs-devel \
rpm-build \ # if you want to build an RPM binary package
Ubuntu 18.04
""""""""""""
End of Life: April 2028
Install Repositories
.. code-block:: bash
sudo apt update && sudo apt install \
software-properties-common \
&& add-apt-repository ppa:savoury1/graphics && \
add-apt-repository ppa:savoury1/multimedia && \
add-apt-repository ppa:savoury1/ffmpeg4 && \
add-apt-repository ppa:savoury1/boost-defaults-1.71 && \
add-apt-repository ppa:ubuntu-toolchain-r/test && \
Install Requirements
.. code-block:: bash
sudo apt install \
build-essential \
cmake \
gcc-10 \
git \
g++-10 \
libavdevice-dev \
libboost-filesystem1.71-dev \
libboost-log1.71-dev \
libboost-regex1.71-dev \
libboost-thread1.71-dev \
libcap-dev \ # KMS
libdrm-dev \ # KMS
libevdev-dev \
libpulse-dev \
libopus-dev \
libssl-dev \
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
wget \
Update gcc alias
.. code-block:: bash
update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 --slave /usr/bin/g++ g++ /usr/bin/g++-10
Install CuDA
.. code-block:: bash
wget https://developer.download.nvidia.com/compute/cuda/11.4.2/local_installers/cuda_11.4.2_470.57.02_linux.run --progress=bar:force:noscroll -q --show-progress -O ./cuda.run && chmod a+x ./cuda.run
./cuda.run --silent --toolkit --toolkitpath=/usr --no-opengl-libs --no-man-page --no-drm && rm ./cuda.run
Install CMake
.. code-block:: bash
wget https://cmake.org/files/v3.22/cmake-3.22.2-linux-x86_64.sh
mkdir /opt/cmake
sh /cmake-3.22.2-linux-x86_64.sh --prefix=/opt/cmake --skip-license
ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake
cmake --version
Ubuntu 20.04
""""""""""""
End of Life: April 2030
Install Requirements
.. code-block:: bash
sudo apt update && sudo apt install \
build-essential \
cmake \
git \
g++-10 \
libavdevice-dev \
libboost-filesystem-dev \
libboost-log-dev \
libboost-thread-dev \
libcap-dev \ # KMS
libdrm-dev \ # KMS
libevdev-dev \
libpulse-dev \
libopus-dev \
libssl-dev \
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
wget \
Update gcc alias
.. code-block:: bash
update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 --slave /usr/bin/g++ g++ /usr/bin/g++-10
Install CuDA
.. code-block:: bash
wget https://developer.download.nvidia.com/compute/cuda/11.4.2/local_installers/cuda_11.4.2_470.57.02_linux.run --progress=bar:force:noscroll -q --show-progress -O ./cuda.run && chmod a+x ./cuda.run
./cuda.run --silent --toolkit --toolkitpath=/usr --no-opengl-libs --no-man-page --no-drm && rm ./cuda.run
Ubuntu 21.10
""""""""""""
End of Life: July 2022
Install Requirements
.. code-block:: bash
sudo apt update && sudo apt install \
build-essential \
cmake \
git \
libavdevice-dev \
libboost-filesystem-dev \
libboost-log-dev \
libboost-thread-dev \
libcap-dev \ # KMS
libdrm-dev \ # KMS
libevdev-dev \
libpulse-dev \
libopus-dev \
libssl-dev \
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
nvidia-cuda-dev \ # Cuda, NvFBC
nvidia-cuda-toolkit \ # Cuda, NvFBC
Ubuntu 22.04
""""""""""""
End of Life: April 2027
.. Todo:: Create Ubuntu 22.04 Dockerfile and complete this documentation.
Build
-----
.. Caution:: Ensure you are in the build directory created during the clone step earlier before continuing.
Debian based OSes
.. code-block:: bash
cmake -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 ..
Red Hat based Oses
.. code-block:: bash
cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
Finally
.. code-block:: bash
make -j ${nproc}

41
docs/source/building/macos.rst Normal file
View file

@ -0,0 +1,41 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/macos.rst
MacOS
=====
Requirements
------------
MacOS Big Sur and Xcode 12.5+
Use either `MacPorts <https://www.macports.org>`_ or `Homebrew <https://brew.sh>`_
MacPorts
""""""""
Install Requirements
.. code-block:: bash
sudo port install cmake boost libopus ffmpeg
Homebrew
""""""""
Install Requirements
.. code-block:: bash
brew install boost cmake ffmpeg libopusenc
# if there are issues with an SSL header that is not found:
cd /usr/local/include
ln -s ../opt/openssl/include/openssl .
Build
-----
.. Caution:: Ensure you are in the build directory created during the clone step earlier before continuing.
.. code-block:: bash
cmake ..
make -j ${nproc}
If cmake fails complaining to find Boost, try to set the path explicitly.
``cmake -DBOOST_ROOT=[boost path] ..``, e.g., ``cmake -DBOOST_ROOT=/opt/local/libexec/boost/1.76 ..``

22
docs/source/building/windows.rst Normal file
View file

@ -0,0 +1,22 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/windows.rst
Windows
=======
Requirements
------------
First you need to install `MSYS2 <https://www.msys2.org>`_, then startup "MSYS2 MinGW 64-bit" and install the
following packages using:
.. code-block:: batch
pacman -S mingw-w64-x86_64-binutils mingw-w64-x86_64-openssl mingw-w64-x86_64-cmake mingw-w64-x86_64-toolchain mingw-w64-x86_64-opus mingw-w64-x86_64-x265 mingw-w64-x86_64-boost git mingw-w64-x86_64-make cmake make gcc
Build
-----
.. Caution:: Ensure you are in the build directory created during the clone step earlier before continuing.
.. code-block:: batch
cmake -G"Unix Makefiles" ..
mingw32-make

88
docs/source/conf.py Normal file
View file

@ -0,0 +1,88 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# standard imports
from datetime import datetime
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os
# import sys
script_dir = os.path.dirname(os.path.abspath(__file__)) # the directory of this file
source_dir = os.path.dirname(script_dir) # the source folder directory
root_dir = os.path.dirname(source_dir) # the root folder directory
# -- Project information -----------------------------------------------------
project = 'Sunshine'
copyright = f'{datetime.now ().year}, {project}'
author = 'ReenigneArcher'
# The full version, including alpha/beta/rc tags
# version = '0.13.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'm2r2', # enable markdown files
'sphinx.ext.autosectionlabel',
'sphinx.ext.todo', # enable to-do sections
'sphinx.ext.viewcode' # add links to view source code
]
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['toc.rst']
# Extensions to include.
source_suffix = ['.rst', '.md']
# -- Options for HTML output -------------------------------------------------
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
html_logo = os.path.join(root_dir, 'sunshine.ico')
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
# 'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard
# 'analytics_anonymize_ip': False,
'logo_only': False,
'display_version': False,
'prev_next_buttons_location': 'bottom',
'style_external_links': True,
'vcs_pageview_mode': 'blob',
# 'style_nav_header_background': 'white',
# Toc options
'collapse_navigation': True,
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False,
}
# extension config options
autosectionlabel_prefix_document = True # Make sure the target is unique
todo_include_todos = True

32
docs/source/contributing/contributing.rst Normal file
View file

@ -0,0 +1,32 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/contributing/contributing.rst
Contributing
============
#. Fork the repo on GitHub
#. Create a new branch for the feature you are adding or the issue you are fixing
.. Tip:: Base the new branch off the `nightly` branch. It will make your life easier when you submit the PR!
#. Make changes, push commits, etc.
#. Files should contain an empty line at the end.
#. Document your code!
#. Test your code!
#. When ready create a PR to this repo on the `nightly` branch.
.. Hint:: If you accidentally make your PR against a different branch, a bot will comment letting you know it's on
the wrong branch. Don't worry. You can edit the PR to change the target branch. There is no reason to close the
PR!
.. Note:: Draft PRs are also welcome as you work through issues. The benefit of creating a draft PR is that an
automated build can run in a github runner.
.. Attention:: Do not expect partially complete PRs to be merged. These topics will be considered before merging.
- Does the code follows the style guidelines of this project?
.. Tip:: Look at examples of existing code in the project!
- Is the code well commented?
- Were documentation blocks updated for new or modified components?
.. Note:: Developers and maintainers will attempt to assist with challenging issues.

80
docs/source/contributing/localization.rst Normal file
View file

@ -0,0 +1,80 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/contributing/localization.rst
Localization
============
Sunshine is being localized into various languages. The default language is `en` (English) and is highlighted green.
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=de&style=for-the-badge&query=%24.progress.0.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=green&label=en&style=for-the-badge&query=%24.progress.1.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=en-GB&style=for-the-badge&query=%24.progress.2.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=en-US&style=for-the-badge&query=%24.progress.3.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=es-ES&style=for-the-badge&query=%24.progress.4.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=fr&style=for-the-badge&query=%24.progress.5.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=it&style=for-the-badge&query=%24.progress.6.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=ru&style=for-the-badge&query=%24.progress.7.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json
Graph
.. image:: https://badges.awesome-crowdin.com/translation-15178612-503956.png
CrowdIn
-------
The translations occur on
`CrowdIn <https://crowdin.com/project/sunshinestream>`_. Feel free to contribute to localization there.
Only elements of the API are planned to be translated.
.. Note:: The rest API has not yet been implemented.
Translations Basics
- The brand names `SunshineStream` and `Sunshine` should never be translated.
- Other brand names should never be translated.
Examples:
- AMD
- Nvidia
CrowdIn Integration
How does it work?
When a change is made to sunshine source code, a workflow generates new translation templates
that get pushed to CrowdIn automatically.
When translations are updated on CrowdIn, a push gets made to the `l10n_nightly` branch and a PR is made against the
`nightly` branch. Once PR is merged, all updated translations are part of the project and will be included in the
next release.
Extraction
----------
There should be minimal cases where strings need to be extracted from source code; however it may be necessary in some
situations. For example if a system tray icon is added it should be localized as it is user interfacing.
- Wrap the string to be extracted in a function as shown.
.. code-block:: cpp
#include <boost/locale.hpp>
boost::locale::translate("Hello world!")
.. Warning:: This is for information only. Contributors should never include manually updated template files, or
manually compiled language files in Pull Requests.
Strings are automatically extracted from the code to the `locale/sunshine.po` template file. The generated file is
used by CrowdIn to generate language specific template files. The file is generated using the
`.github/workflows/localize.yml` workflow and is run on any push event into the `nightly` branch. Jobs are only run if
any of the following paths are modified.
.. code-block:: yaml
- 'sunshine/**'
When testing locally it may be desirable to manually extract, initialize, update, and compile strings. Python is
required for this, along with the dependencies in the `./scripts/requirements.txt` file.
Extract, initialize, and update
.. code-block:: bash
python ./scripts/_locale.py --extract --init --update
Compile
.. code-block:: bash
python ./scripts/_locale.py --compile

42
docs/source/contributing/testing.rst Normal file
View file

@ -0,0 +1,42 @@
:github_url: https://github.com/RetroArcher/RetroArcher/tree/nightly/docs/source/contributing/testing.rst
Testing
=======
Clang Format
------------
Source code is tested against the `.clang-format` file for linting errors. The workflow file responsible for clang
format testing is `.github/workflows/clang.yml`.
Test clang-format locally.
.. Todo:: This documentation needs to be improved.
.. code-block:: bash
clang-format ...
Sphinx
------
Sunshine uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_ for documentation building. Sphinx is included
in the `./scripts/requirements.txt` file. Python is required to build sphinx docs. Installation and setup of python
will not be covered here.
The config file for Sphinx is `docs/source/conf.py`. This is already included in the repo and should not be modified.
Test with Sphinx
.. code-block:: bash
cd docs
make html
Alternatively
.. code-block:: bash
cd docs
sphinx-build -b html source build
Unit Testing
------------
.. Todo:: Sunshine does not currently have any unit tests. If you would like to help us improve please get in contact
with us, or make a PR with suggested changes.

7
docs/source/index.rst Normal file
View file

@ -0,0 +1,7 @@
:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/index.rst
SunshineStream has this documentation hosted on `Read the Docs <http://sunshinestream.readthedocs.io/>`_.
Table of Contents
=================
.. include:: toc.rst

27
docs/source/toc.rst Normal file
View file

@ -0,0 +1,27 @@
.. toctree::
:maxdepth: 2
:caption: About
about/overview
about/installation
about/docker
about/third_party_packages
about/usage
about/advanced_usage
.. toctree::
:maxdepth: 2
:caption: Build
building/build
building/linux
building/macos
building/windows
.. toctree::
:maxdepth: 2
:caption: Contributing
contributing/contributing
contributing/localization
contributing/testing