izackp/Apollo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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
parent 4bdf8375cc
commit 536df759ae
35 changed files with 2350 additions and 342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.