diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d4f34ea7..5ae7e5a6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,7 +12,12 @@ build: tools: python: "3.11" apt_packages: - - graphviz + - graphviz # required to build diagrams + - libboost-locale-dev # required for rstcheck in cpp code block + jobs: + post_build: + - rstcheck -r . # lint rst files + # - rstfmt --check --diff -w 120 . # check rst formatting # submodules required for include statements submodules: diff --git a/.rstcheck.cfg b/.rstcheck.cfg new file mode 100644 index 00000000..86108587 --- /dev/null +++ b/.rstcheck.cfg @@ -0,0 +1,9 @@ +# configuration file for rstcheck, an rst linting tool +# https://rstcheck.readthedocs.io/en/latest/usage/config + +[rstcheck] +ignore_directives = + doxygenfile, + include, + mdinclude, + todo, diff --git a/README.rst b/README.rst index b84bfa29..929eba47 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ Overview ======== -LizardByte has the full documentation hosted on `Read the Docs `_. +LizardByte has the full documentation hosted on `Read the Docs `__. About ----- @@ -104,7 +104,7 @@ Support ------- Our support methods are listed in our -`LizardByte Docs `_. +`LizardByte Docs `__. Downloads --------- diff --git a/docs/requirements.txt b/docs/requirements.txt index 5a878ff0..401effd3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,7 @@ breathe==4.35.0 furo==2023.7.26 m2r2==0.3.3.post2 +rstcheck[sphinx]==6.1.2 +rstfmt==0.0.14 Sphinx==7.1.2 sphinx-copybutton==0.5.2 diff --git a/docs/source/about/advanced_usage.rst b/docs/source/about/advanced_usage.rst index 9730b374..2a6ba5ba 100644 --- a/docs/source/about/advanced_usage.rst +++ b/docs/source/about/advanced_usage.rst @@ -226,7 +226,7 @@ keybindings **Description** Sometimes it may be useful to map keybindings. Wayland won't allow clients to capture the Win Key for example. - .. Tip:: See `virtual key codes `_ + .. Tip:: See `virtual key codes `__ .. Hint:: keybindings needs to have a multiple of two elements. @@ -438,8 +438,8 @@ audio_sink **macOS** Sunshine can only access microphones on macOS due to system limitations. To stream system audio use - `Soundflower `_ or - `BlackHole `_. + `Soundflower `__ or + `BlackHole `__. **Windows** .. code-block:: batch @@ -485,7 +485,7 @@ virtual_sink - Steam must be installed. - Enable `install_steam_audio_drivers`_ or use Steam Remote Play at least once to install the drivers. - - `Virtual Audio Cable `_ (macOS, Windows) + - `Virtual Audio Cable `__ (macOS, Windows) **Example** .. code-block:: text @@ -862,8 +862,8 @@ capture ========= =========== nvfbc Use NVIDIA Frame Buffer Capture to capture direct to GPU memory. This is usually the fastest method for NVIDIA cards. For GeForce cards it will only work with drivers patched with - `nvidia-patch `_ - or `nvlax `_. + `nvidia-patch `__ + or `nvlax `__. wlr Capture for wlroots based Wayland compositors via DMA-BUF. kms DRM/KMS screen capture from the kernel. This requires that sunshine has cap_sys_admin capability. See :ref:`Linux Setup `. @@ -914,7 +914,7 @@ sw_preset .. Note:: This option only applies when using software `encoder`_. - .. Note:: From `FFmpeg `_. + .. Note:: From `FFmpeg `__. A preset is a collection of options that will provide a certain encoding speed to compression ratio. A slower preset will provide better compression (compression is quality per filesize). This means that, for example, if @@ -958,7 +958,7 @@ sw_tune .. Note:: This option only applies when using software `encoder`_. - .. Note:: From `FFmpeg `_. + .. Note:: From `FFmpeg `__. You can optionally use -tune to change settings based upon the specifics of your input. @@ -993,7 +993,7 @@ nv_preset The encoder preset to use. .. Note:: This option only applies when using nvenc `encoder`_. For more information on the presets, see - `nvenc preset migration guide `_. + `nvenc preset migration guide `__. **Choices** diff --git a/docs/source/about/app_examples.rst b/docs/source/about/app_examples.rst index aa5b606f..b2fea331 100644 --- a/docs/source/about/app_examples.rst +++ b/docs/source/about/app_examples.rst @@ -169,7 +169,7 @@ Changing Resolution and Refresh Rate (macOS) .. Note:: This example uses the `displayplacer` tool to change the resolution. This tool can be installed following instructions in their - `GitHub repository `_. + `GitHub repository `__. +----------------------+-----------------------------------------------------------------------------------------------+ | **Field** | **Value** | @@ -186,7 +186,7 @@ Changing Resolution and Refresh Rate (Windows) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. Note:: This example uses the `QRes` tool to change the resolution and refresh rate. - This tool can be downloaded from their `SourceForge repository `_. + This tool can be downloaded from their `SourceForge repository `__. +----------------------+------------------------------------------------------------------------------------------------------------------+ | **Field** | **Value** | diff --git a/docs/source/about/installation.rst b/docs/source/about/installation.rst index 054f9a92..86262e8f 100644 --- a/docs/source/about/installation.rst +++ b/docs/source/about/installation.rst @@ -27,7 +27,7 @@ Follow the instructions for your preferred package type below. CUDA is used for NVFBC capture. -.. Tip:: See `CUDA GPUS `_ to cross reference Compute Capability to your GPU. +.. Tip:: See `CUDA GPUS `__ to cross reference Compute Capability to your GPU. .. table:: :widths: auto @@ -128,7 +128,7 @@ Uninstall: Flatpak Package ^^^^^^^^^^^^^^^ -#. Install `Flatpak `_ as required. +#. Install `Flatpak `__ as required. #. Download ``sunshine_{arch}.flatpak`` and run the following code. .. Note:: Be sure to replace ``{arch}`` with the architecture for your operating system. @@ -205,7 +205,7 @@ Uninstall: Portfile ^^^^^^^^ -#. Install `MacPorts `_ +#. Install `MacPorts `__ #. Update the Macports sources. .. code-block:: bash @@ -244,7 +244,7 @@ Installer .. Attention:: You should carefully select or unselect the options you want to install. Do not blindly install or enable features. -To uninstall, find Sunshine in the list `here `_ and select "Uninstall" from the overflow +To uninstall, find Sunshine in the list `here `__ and select "Uninstall" from the overflow menu. Different versions of Windows may provide slightly different steps for uninstall. Standalone diff --git a/docs/source/about/usage.rst b/docs/source/about/usage.rst index 3e956559..189981ce 100644 --- a/docs/source/about/usage.rst +++ b/docs/source/about/usage.rst @@ -31,7 +31,7 @@ Usage #. Configure Sunshine in the web ui - The web ui is available on `https://localhost:47990 `_ by default. You may replace + The web ui is available on `https://localhost:47990 `__ by default. You may replace `localhost` with your internal ip address. .. Attention:: Ignore any warning given by your browser about "insecure website". This is due to the SSL certificate @@ -86,7 +86,7 @@ Sunshine needs access to `uinput` to create mouse and gamepad events. - filename: ``~/.config/systemd/user/sunshine.service`` - contents: - .. code-block:: + .. code-block:: cfg [Unit] Description=Sunshine self-hosted game stream host for Moonlight. @@ -148,8 +148,8 @@ Sunshine needs access to `uinput` to create mouse and gamepad events. macOS ^^^^^ Sunshine can only access microphones on macOS due to system limitations. To stream system audio use -`Soundflower `_ or -`BlackHole `_. +`Soundflower `__ or +`BlackHole `__. .. Note:: Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key. @@ -163,7 +163,7 @@ Configure autostart service Windows ^^^^^^^ -For gamepad support, install `ViGEmBus `_ +For gamepad support, install `ViGEmBus `__ Sunshine firewall **Add rule** @@ -280,7 +280,7 @@ You must have an HDR-capable display or EDID emulator dongle connected to your h Tutorials --------- -Tutorial videos are available `here `_. +Tutorial videos are available `here `__. .. admonition:: Community! diff --git a/docs/source/building/build.rst b/docs/source/building/build.rst index 013c9709..97693205 100644 --- a/docs/source/building/build.rst +++ b/docs/source/building/build.rst @@ -1,6 +1,6 @@ Build ===== -Sunshine binaries are built using `CMake `_. Cross compilation is not +Sunshine binaries are built using `CMake `__. Cross compilation is not supported. That means the binaries must be built on the target operating system and architecture. Building Locally @@ -8,7 +8,7 @@ Building Locally Clone ^^^^^ -Ensure `git `_ is installed and run the following: +Ensure `git `__ is installed and run the following: .. code-block:: bash git clone https://github.com/lizardbyte/sunshine.git --recurse-submodules diff --git a/docs/source/building/linux.rst b/docs/source/building/linux.rst index 5d7d0b4e..3099cda4 100644 --- a/docs/source/building/linux.rst +++ b/docs/source/building/linux.rst @@ -174,10 +174,10 @@ CUDA If the version of CUDA available from your distro is not adequate, manually install CUDA. .. Tip:: The version of CUDA you use will determine compatibility with various GPU generations. - See `CUDA compatibility `_ for more info. + See `CUDA compatibility `__ for more info. Select the appropriate run file based on your desired CUDA version and architecture according to - `CUDA Toolkit Archive `_. + `CUDA Toolkit Archive `__. .. code-block:: bash diff --git a/docs/source/building/macos.rst b/docs/source/building/macos.rst index 5ff3e74e..40cc53a9 100644 --- a/docs/source/building/macos.rst +++ b/docs/source/building/macos.rst @@ -5,7 +5,7 @@ Requirements ------------ macOS Big Sur and Xcode 12.5+ -Use either `MacPorts `_ or `Homebrew `_ +Use either `MacPorts `__ or `Homebrew `__ MacPorts """""""" diff --git a/docs/source/building/windows.rst b/docs/source/building/windows.rst index 0cfb53a4..a51b6485 100644 --- a/docs/source/building/windows.rst +++ b/docs/source/building/windows.rst @@ -3,7 +3,7 @@ Windows Requirements ------------ -First you need to install `MSYS2 `_, then startup "MSYS2 MinGW 64-bit" and execute the following +First you need to install `MSYS2 `__, then startup "MSYS2 MinGW 64-bit" and execute the following codes. Update all packages: @@ -21,7 +21,7 @@ Install dependencies: npm dependencies ---------------- -Install nodejs and npm. Downloads available `here `_. +Install nodejs and npm. Downloads available `here `__. Install npm dependencies. .. code-block:: bash diff --git a/docs/source/contributing/contributing.rst b/docs/source/contributing/contributing.rst index 217bda13..a50300d2 100644 --- a/docs/source/contributing/contributing.rst +++ b/docs/source/contributing/contributing.rst @@ -2,4 +2,4 @@ Contributing ============ Read our contribution guide in our organization level -`docs `_. +`docs `__. diff --git a/docs/source/contributing/localization.rst b/docs/source/contributing/localization.rst index dc3e26da..e6cea955 100644 --- a/docs/source/contributing/localization.rst +++ b/docs/source/contributing/localization.rst @@ -17,7 +17,7 @@ Graph CrowdIn ------- The translations occur on -`CrowdIn `_. Feel free to contribute to localization there. +`CrowdIn `__. Feel free to contribute to localization there. Only elements of the API are planned to be translated. .. Attention:: The rest API has not yet been implemented. @@ -49,10 +49,12 @@ situations. For example if a system tray icon is added it should be localized as .. code-block:: cpp #include - boost::locale::translate("Hello world!") + #include + + std::string msg = boost::locale::translate("Hello world!"); .. Tip:: More examples can be found in the documentation for - `boost locale `_. + `boost locale `__. .. Warning:: This is for information only. Contributors should never include manually updated template files, or manually compiled language files in Pull Requests. @@ -68,7 +70,7 @@ any of the following paths are modified. When testing locally it may be desirable to manually extract, initialize, update, and compile strings. Python is required for this, along with the python dependencies in the `./scripts/requirements.txt` file. Additionally, -`xgettext `_ must be installed. +`xgettext `__ must be installed. **Extract, initialize, and update** .. code-block:: bash diff --git a/docs/source/contributing/testing.rst b/docs/source/contributing/testing.rst index aca4a82d..716e21ce 100644 --- a/docs/source/contributing/testing.rst +++ b/docs/source/contributing/testing.rst @@ -13,12 +13,12 @@ Test clang-format locally. Sphinx ------ -Sunshine uses `Sphinx `_ for documentation building. Sphinx, along with other +Sunshine uses `Sphinx `__ for documentation building. Sphinx, along with other required python dependencies are included in the `./docs/requirements.txt` file. Python is required to build sphinx docs. Installation and setup of python will not be covered here. Doxygen is used to generate the XML files required by Sphinx. Doxygen can be obtained from -`Doxygen downloads `_. Ensure that the `doxygen` executable is in your path. +`Doxygen downloads `__. Ensure that the `doxygen` executable is in your path. The config file for Sphinx is `docs/source/conf.py`. This is already included in the repo and should not be modified. @@ -37,6 +37,21 @@ Test with Sphinx cd docs sphinx-build -b html source build +Lint with rstcheck + .. code-block:: bash + + rstcheck -r . + +Check formatting with rstfmt + .. code-block:: bash + + rstfmt --check --diff -w 120 . + +Format inplace with rstfmt + .. code-block:: bash + + rstfmt -w 120 . + Unit Testing ------------ .. Todo:: Sunshine does not currently have any unit tests. If you would like to help us improve please get in contact diff --git a/docs/source/gamestream/gamestream.rst b/docs/source/gamestream/gamestream.rst index aed014b2..a0cabbd3 100644 --- a/docs/source/gamestream/gamestream.rst +++ b/docs/source/gamestream/gamestream.rst @@ -7,7 +7,7 @@ outperforms GameStream, so rest assured that Sunshine will be equally performant Migration --------- We have developed a simple migration tool to help you migrate your GameStream games and apps to Sunshine automatically. -Please check out our `GSMS `_ project if you're interested in an automated +Please check out our `GSMS `__ project if you're interested in an automated migration option. At the time of writing this GSMS offers the ability to migrate your custom games and apps. The working directory, command, and image are all set in Sunshine's ``apps.json`` file. The box-art image is also copied to a specified directory. diff --git a/docs/source/legal/legal.rst b/docs/source/legal/legal.rst index 13bc3660..4fb55b04 100644 --- a/docs/source/legal/legal.rst +++ b/docs/source/legal/legal.rst @@ -4,7 +4,7 @@ Legal any legal questions or concerns about using Sunshine, we recommend consulting with a lawyer. Sunshine is licensed under the GPL-3.0 license, which allows for free use and modification of the software. -The full text of the license can be reviewed `here `_. +The full text of the license can be reviewed `here `__. Commercial Use -------------- diff --git a/docs/source/source/src.rst b/docs/source/source/src.rst index b5b79228..bdba0c35 100644 --- a/docs/source/source/src.rst +++ b/docs/source/source/src.rst @@ -10,7 +10,7 @@ Example Documentation Blocks **file.h** -.. code-block:: cpp +.. code-block:: c // functions int main(int argc, char *argv[]); diff --git a/docs/source/troubleshooting/general.rst b/docs/source/troubleshooting/general.rst index 3b6d6aad..a936f35a 100644 --- a/docs/source/troubleshooting/general.rst +++ b/docs/source/troubleshooting/general.rst @@ -6,7 +6,7 @@ Forgotten Credentials If you forgot your credentials to the web UI, try this. .. code-block:: bash - sunshine --creds + sunshine --creds {new-username} {new-password} Web UI Access ------------- @@ -17,8 +17,8 @@ Nvidia issues ------------- NvFBC, NvENC, or general issues with Nvidia graphics card. - Consumer grade Nvidia cards are software limited to a specific number of encodes. See - `Video Encode and Decode GPU Support Matrix `_ + `Video Encode and Decode GPU Support Matrix `__ for more info. - You can usually bypass the restriction with a driver patch. See Keylase's - `Linux `_ - or `Windows `_ patches for more guidance. + `Linux `__ + or `Windows `__ patches for more guidance. diff --git a/docs/source/troubleshooting/linux.rst b/docs/source/troubleshooting/linux.rst index 809cbf5e..5646a1d2 100644 --- a/docs/source/troubleshooting/linux.rst +++ b/docs/source/troubleshooting/linux.rst @@ -10,7 +10,7 @@ Due to legal concerns, Mesa has disabled hardware decoding and encoding by defau Error: Could not open codec [h264_vaapi]: Function not implemented If you see the above error in the Sunshine logs, compiling `Mesa` -manually, may be required. See the official Mesa3D `Compiling and Installing `_ +manually, may be required. See the official Mesa3D `Compiling and Installing `__ documentation for instructions. .. Important:: You must re-enable the disabled encoders. You can do so, by passing the following argument to the build @@ -21,7 +21,7 @@ documentation for instructions. -Dvideo-codecs=h264enc,h265enc .. Note:: Other build options are listed in the - `meson options `_ file. + `meson options `__ file. KMS Streaming fails ------------------- diff --git a/docs/source/troubleshooting/windows.rst b/docs/source/troubleshooting/windows.rst index 31a1a6ba..a1e08c7a 100644 --- a/docs/source/troubleshooting/windows.rst +++ b/docs/source/troubleshooting/windows.rst @@ -3,4 +3,4 @@ Windows No gamepad detected ------------------- -#. Verify that you've installed `ViGEmBus `_. +#. Verify that you've installed `ViGEmBus `__.