diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d4f34ea7c..5ae7e5a61 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 000000000..861085875 --- /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 b84bfa29e..929eba478 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 5a878ff01..401effd3d 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 9730b3748..2a6ba5bab 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 aa5b606f4..b2fea331c 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 054f9a924..86262e8fa 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 3e956559d..189981ce6 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 013c9709a..97693205a 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 5d7d0b4e5..3099cda43 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 5ff3e74e9..40cc53a91 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 0cfb53a48..a51b64853 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 217bda130..a50300d23 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 dc3e26da8..e6cea9558 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 aca4a82dc..716e21ce2 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 aed014b28..a0cabbd3f 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 13bc36601..4fb55b045 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 b5b79228c..bdba0c359 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 3b6d6aad2..a936f35aa 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 809cbf5e3..5646a1d2f 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 31a1a6baf..a1e08c7a6 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 `__.