docs: lint rst files (#1581)

LizardByte · Aug 31, 2023 · a3eec98 · a3eec98
1 parent 9327489
commit a3eec98
Show file tree

Hide file tree

Showing 21 changed files with 81 additions and 48 deletions.
diff --git 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
@@ -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
@@ -1,6 +1,6 @@
 Overview
 ========
-LizardByte has the full documentation hosted on `Read the Docs <https://sunshinestream.readthedocs.io/>`_.
+LizardByte has the full documentation hosted on `Read the Docs <https://sunshinestream.readthedocs.io/>`__.
 
 About
 -----
@@ -104,7 +104,7 @@ Support
 -------
 
 Our support methods are listed in our
-`LizardByte Docs <https://lizardbyte.readthedocs.io/en/latest/about/support.html>`_.
+`LizardByte Docs <https://lizardbyte.readthedocs.io/en/latest/about/support.html>`__.
 
 Downloads
 ---------

diff --git 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
@@ -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 <https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes>`_
+   .. Tip:: See `virtual key codes <https://docs.microsoft.com/en-us/windows/win32/inputdev/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 <https://github.com/mattingalls/Soundflower>`_ or
-         `BlackHole <https://github.com/ExistentialAudio/BlackHole>`_.
+         `Soundflower <https://github.com/mattingalls/Soundflower>`__ or
+         `BlackHole <https://github.com/ExistentialAudio/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 <https://vb-audio.com/Cable/>`_ (macOS, Windows)
+      - `Virtual Audio Cable <https://vb-audio.com/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 <https://github.com/keylase/nvidia-patch/>`_
-              or `nvlax <https://github.com/illnyang/nvlax/>`_.
+              `nvidia-patch <https://github.com/keylase/nvidia-patch/>`__
+              or `nvlax <https://github.com/illnyang/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 <about/usage:setup>`.
@@ -914,7 +914,7 @@ sw_preset
 
    .. Note:: This option only applies when using software `encoder`_.
 
-   .. Note:: From `FFmpeg <https://trac.ffmpeg.org/wiki/Encode/H.264#preset>`_.
+   .. Note:: From `FFmpeg <https://trac.ffmpeg.org/wiki/Encode/H.264#preset>`__.
 
          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 <https://trac.ffmpeg.org/wiki/Encode/H.264#preset>`_.
+   .. Note:: From `FFmpeg <https://trac.ffmpeg.org/wiki/Encode/H.264#preset>`__.
 
          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 <https://docs.nvidia.com/video-technologies/video-codec-sdk/nvenc-preset-migration-guide/>`_.
+      `nvenc preset migration guide <https://docs.nvidia.com/video-technologies/video-codec-sdk/nvenc-preset-migration-guide/>`__.
 
 **Choices**
 

diff --git 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 <https://github.com/jakehilborn/displayplacer>`_.
+   `GitHub repository <https://github.com/jakehilborn/displayplacer>`__.
 
 +----------------------+-----------------------------------------------------------------------------------------------+
 | **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 <https://sourceforge.net/projects/qres/>`_.
+   This tool can be downloaded from their `SourceForge repository <https://sourceforge.net/projects/qres/>`__.
 
 +----------------------+------------------------------------------------------------------------------------------------------------------+
 | **Field**            | **Value**                                                                                                        |

diff --git 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 <https://developer.nvidia.com/cuda-gpus>`_ to cross reference Compute Capability to your GPU.
+.. Tip:: See `CUDA GPUS <https://developer.nvidia.com/cuda-gpus>`__ to cross reference Compute Capability to your GPU.
 
 .. table::
    :widths: auto
@@ -128,7 +128,7 @@ Uninstall:
 
 Flatpak Package
 ^^^^^^^^^^^^^^^
-#. Install `Flatpak <https://flatpak.org/setup/>`_ as required.
+#. Install `Flatpak <https://flatpak.org/setup/>`__ 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 <https://www.macports.org>`_
+#. Install `MacPorts <https://www.macports.org>`__
 #. 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 <ms-settings:installed-apps>`_ and select "Uninstall" from the overflow
+To uninstall, find Sunshine in the list `here <ms-settings:installed-apps>`__ 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
@@ -31,7 +31,7 @@ Usage
 
 #. Configure Sunshine in the web ui
 
-   The web ui is available on `https://localhost:47990 <https://localhost:47990>`_ by default. You may replace
+   The web ui is available on `https://localhost:47990 <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 <https://github.com/mattingalls/Soundflower>`_ or
-`BlackHole <https://github.com/ExistentialAudio/BlackHole>`_.
+`Soundflower <https://github.com/mattingalls/Soundflower>`__ or
+`BlackHole <https://github.com/ExistentialAudio/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 <https://github.com/ViGEm/ViGEmBus/releases/latest>`_
+For gamepad support, install `ViGEmBus <https://github.com/ViGEm/ViGEmBus/releases/latest>`__
 
 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 <https://www.youtube.com/playlist?list=PLMYr5_xSeuXAbhxYHz86hA1eCDugoxXY0>`_.
+Tutorial videos are available `here <https://www.youtube.com/playlist?list=PLMYr5_xSeuXAbhxYHz86hA1eCDugoxXY0>`__.
 
 .. admonition:: Community!
 

diff --git a/docs/source/building/build.rst b/docs/source/building/build.rst
@@ -1,14 +1,14 @@
 Build
 =====
-Sunshine binaries are built using `CMake <https://cmake.org/>`_. Cross compilation is not
+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:
+Ensure `git <https://git-scm.com/>`__ 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
@@ -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 <https://docs.nvidia.com/deploy/cuda-compatibility/index.html>`_ for more info.
+   See `CUDA compatibility <https://docs.nvidia.com/deploy/cuda-compatibility/index.html>`__ for more info.
 
    Select the appropriate run file based on your desired CUDA version and architecture according to
-   `CUDA Toolkit Archive <https://developer.nvidia.com/cuda-toolkit-archive>`_.
+   `CUDA Toolkit Archive <https://developer.nvidia.com/cuda-toolkit-archive>`__.
 
 .. code-block:: bash
 

diff --git 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 <https://www.macports.org>`_ or `Homebrew <https://brew.sh>`_
+Use either `MacPorts <https://www.macports.org>`__ or `Homebrew <https://brew.sh>`__
 
 MacPorts
 """"""""

diff --git a/docs/source/building/windows.rst b/docs/source/building/windows.rst
@@ -3,7 +3,7 @@ Windows
 
 Requirements
 ------------
-First you need to install `MSYS2 <https://www.msys2.org>`_, then startup "MSYS2 MinGW 64-bit" and execute the following
+First you need to install `MSYS2 <https://www.msys2.org>`__, 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 <https://nodejs.org/en/download/>`_.
+Install nodejs and npm. Downloads available `here <https://nodejs.org/en/download/>`__.
 
 Install npm dependencies.
    .. code-block:: bash

diff --git 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 <https://lizardbyte.readthedocs.io/en/latest/developers/contributing.html>`_.
+`docs <https://lizardbyte.readthedocs.io/en/latest/developers/contributing.html>`__.
diff --git a/docs/source/contributing/localization.rst b/docs/source/contributing/localization.rst
@@ -17,7 +17,7 @@ Graph
 CrowdIn
 -------
 The translations occur on
-`CrowdIn <https://crowdin.com/project/sunshinestream>`_. Feel free to contribute to localization there.
+`CrowdIn <https://crowdin.com/project/sunshinestream>`__. 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.hpp>
-      boost::locale::translate("Hello world!")
+      #include <string>
+
+      std::string msg = boost::locale::translate("Hello world!");
 
 .. Tip:: More examples can be found in the documentation for
-   `boost locale <https://www.boost.org/doc/libs/1_70_0/libs/locale/doc/html/messages_formatting.html>`_.
+   `boost locale <https://www.boost.org/doc/libs/1_70_0/libs/locale/doc/html/messages_formatting.html>`__.
 
 .. 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 <https://www.gnu.org/software/gettext/>`_ must be installed.
+`xgettext <https://www.gnu.org/software/gettext/>`__ must be installed.
 
 **Extract, initialize, and update**
    .. code-block:: bash

diff --git a/docs/source/contributing/testing.rst b/docs/source/contributing/testing.rst
@@ -13,12 +13,12 @@ Test clang-format locally.
 
 Sphinx
 ------
-Sunshine uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_ for documentation building. Sphinx, along with other
+Sunshine uses `Sphinx <https://www.sphinx-doc.org/en/master/>`__ 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 <https://www.doxygen.nl/download.html>`_. Ensure that the `doxygen` executable is in your path.
+`Doxygen downloads <https://www.doxygen.nl/download.html>`__. 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
@@ -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 <https://github.com/LizardByte/GSMS>`_ project if you're interested in an automated
+Please check out our `GSMS <https://github.com/LizardByte/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
@@ -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 <https://github.com/LizardByte/Sunshine/blob/master/LICENSE>`_.
+The full text of the license can be reviewed `here <https://github.com/LizardByte/Sunshine/blob/master/LICENSE>`__.
 
 Commercial Use
 --------------

diff --git 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
@@ -6,7 +6,7 @@ Forgotten Credentials
 If you forgot your credentials to the web UI, try this.
    .. code-block:: bash
 
-      sunshine --creds <new username> <new password>
+      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 <https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new>`_
+    `Video Encode and Decode GPU Support Matrix <https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new>`__
     for more info.
   - You can usually bypass the restriction with a driver patch. See Keylase's
-    `Linux <https://github.com/keylase/nvidia-patch>`_
-    or `Windows <https://github.com/keylase/nvidia-patch/blob/master/win>`_ patches for more guidance.
+    `Linux <https://github.com/keylase/nvidia-patch>`__
+    or `Windows <https://github.com/keylase/nvidia-patch/blob/master/win>`__ patches for more guidance.