Merge pull request #238 from SpinalHDL-CN/master

An initial version of Chinese translation.

.github/workflows/push-doc.yml

@@ -18,6 +18,8 @@ jobs:
       sphinx_html_baseurl: 'https://spinalhdl.github.io/SpinalDoc-RTD/master/'
       sphinx_github_url: 'https://github.com/SpinalHDL/SpinalDoc-RTD'
       sphinx_extra_version: 'master'
+
+    if: github.event.head_commit.author.email != 'action.github.com'
     steps:
     - uses: actions/checkout@v3
       with:
@@ -36,6 +38,8 @@ jobs:
         file: pdf.Dockerfile
     - name: Check links
       run: docker run --rm -u $(id -u $USER):$(id -g $USER) -v $PWD:/docs -e sphinx_html_baseurl -e sphinx_github_url spinaldoc-pdf make linkcheck
+    - name: Build zh-cn translated doc
+      run: docker run --rm -u $(id -u $USER):$(id -g $USER) -v $PWD:/docs -e sphinx_html_baseurl -e sphinx_github_url spinaldoc-pdf sphinx-build -b html -D language=zh_CN ./source/ docs/html/zh_CN
     - name: Build multiversioned doc
       run: docker run --rm -u $(id -u $USER):$(id -g $USER) -v $PWD:/docs -e sphinx_html_baseurl -e sphinx_github_url spinaldoc-pdf sphinx-multiversion source docs/html
     - name: Add .nojekill

.github/workflows/test-build.yml

@@ -27,3 +27,7 @@ jobs:
       run: |
         source bin/setup_env.sh
         make html
+    - name: "Test zh-CN doc building"
+      run: |
+        source bin/setup_env.sh
+        make -e SPHINXOPTS="-D language='zh_CN'" html

.github/workflows/update-pot.yml

@@ -0,0 +1,50 @@
+name: "Update translation template pot files."
+
+on:
+  push:
+    branches:
+      - master
+      - dev
+  schedule:
+    # * is a special character in YAML
+    # setup monthly background build
+    - cron: '45 4 20 * *'
+    # gh-pages have a lifetime ?  90 days ? so we do this once a month to refresh
+
+jobs:
+  pots:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: "setup python"
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    - name: "install dependencies"
+      run: |
+        apt-get update -y && apt-get install -y git gettext sphinx-intl
+        pip install -r requirements.txt
+    - uses: ammaraskar/sphinx-problem-matcher@master
+    - name: "update pot"
+      run: |
+        source bin/setup_env.sh
+        make gettext -e BUILDDIR=source/locale/
+    - name: "update po files"
+      run: |
+        source bin/setup_env.sh
+        sphinx-intl update -p source/locale/gettext/ -l zh_CN
+    - name: Commit changes
+      uses: stefanzweifel/git-auto-commit-action@v5
+      with: 
+        commit_message: update .pot files
+        commit_user_email: [email protected]
+        commit_user_name: GiHub Action Bot
+        commit_author: GiHub Action Bot <[email protected]>
+        file_pattern: 'source/locale/*.pot source/locale/*.po'
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: ${{ github.ref }}

.gitignore

@@ -8,9 +8,11 @@ docs/*
 *.bin
 .cache/
 .venv*/
+*.mo
 
 # artifacts from compiling the examples
 examples/project
 .metals
 .scala-build
-.bsp
+.bsp
+.sphinx_matcher.json

README.rst

@@ -51,6 +51,12 @@ and then you can use ``make`` the usual way
 
 all the outputs will be in docs folder (for html: docs/html)
 
+The Chinese version can be built by
+
+.. code:: shell
+
+   make -e SPHINXOPTS="-D language='zh_CN'" html # for html in Chinese
+
 
 With Docker
 -----------

requirements.txt

@@ -3,3 +3,4 @@ sphinx-rtd-theme==1.2.1
 sphinxcontrib-wavedrom==3.0.4
 sphinx-multiversion @ git+https://github.com/samuel-emrys/sphinx-multiversion.git@cd723351f687c98d32834226ae7b3ec9e63bcba5
 sphinx-copybutton==0.5.2
+sphinx-intl==2.1.0

source/_templates/versions.html

@@ -12,9 +12,9 @@
        <dd class="rtd-current-item">
          <a href="#">en</a>
        </dd>
-       <dd>
-         <a href="https://thucgra.github.io/SpinalHDL_Chinese_Doc/">zh_CN</a>
-      </dd>
+       {% for the_language, url in languages %}
+       <dd><a href="{{ url }}/index.html">{{ the_language }}</a></dd>
+       {% endfor %}
     </dl>
     {%- endif %}
     {%- if versions.tags %}

source/conf.py

@@ -223,6 +223,8 @@
     'github_version': os.getenv('GITHUB_REF_NAME', 'master'), # Version
     'conf_py_path': '/source/', # Path in the checkout to the docs root
 
+    'current_language': 'en',
+    'languages': [["zh_CN", "/SpinalDoc-RTD/zh_CN"]],
     'sphinx_latest_version': os.getenv('sphinx_latest_version', None)
 }
 
@@ -366,3 +368,5 @@ def html_context_add_git(attr):
 
 
 html_context = html_context_add_git(html_context)
+locale_dirs = ['locale/']   # path is example but recommended.
+gettext_compact = False     # optional.

source/locale/gettext/SpinalHDL/Data types/AFix.pot

@@ -0,0 +1,193 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2018 - 2024, SpinalHDL
+# This file is distributed under the same license as the SpinalHDL package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: SpinalHDL \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2024-01-02 16:09+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <[email protected]>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#: ../../SpinalHDL/Data types/AFix.rst:5
+msgid "AFix"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:8
+msgid "Description"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:10
+msgid "Auto-ranging Fixed-Point, ``AFix``, is a fixed-point class which tracks the representable range of values while preforming fixed-point operations."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:12
+msgid "**Warning: Much of this code is still under development. API and function calls may change.**"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:14
+msgid "User feedback is appreciated!"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:18
+msgid "Declaration"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:20
+msgid "AFix can be created using bit sizes or exponents:"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:36
+msgid "These will have representable ranges for all bits."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:38
+msgid "For example:"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:40
+msgid "``AFix.U(12 bits)`` will have a range of 0 to 4095."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:42
+msgid "``AFix.SQ(8 bits, 4 bits)`` will have a range of -4096 (-256) to 4095 (255.9375)"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:44
+msgid "``AFix.U(8 exp, 4 exp)`` will have a range of 0 to 256"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:47
+msgid "Custom range ``AFix`` values can be created be directly instantiating the class."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:58
+msgid "The ``maxValue`` and ``minValue`` stores what backing integer values are representable. These values represent the true fixed-point value after multiplying by ``2^exp``."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:61
+msgid "``AFix.U(2 exp, -1 exp)`` can represent: ``0, 0.5, 1.0, 1.5, 2, 2.5, 3, 3.5``"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:64
+msgid "``AFix.S(2 exp, -2 exp)`` can represent: ``-2.0, -1.75, -1.5, -1.25, -1, -0.75, -0.5, -0.25, 0, 0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75``"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:67
+msgid "Exponent values greater 0 are allowed and represent values which are larger than 1."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:69
+msgid "``AFix.S(2 exp, 1 exp)`` can represent: ``-4, 2, 0, 2``"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:72
+msgid "``AFix(8, 16, 2 exp)`` can represent: ``32, 36, 40, 44, 48, 52, 56, 60, 64``"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:75
+msgid "Note: ``AFix`` will use 5 bits to save this type as that can store ``16``, its ``maxValue``."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:79
+msgid "Mathematical Operations"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:81
+msgid "``AFix`` supports Addition (``+``), Subtraction (``-``), and Multiplication (``*``) at the hardware level. Division (``\\``) and Modulo (``%``) operators are provided but are not recommended for hardware elaboration."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:85
+msgid "Operations are preformed as if the ``AFix`` value is a regular ``Int`` number. Signed and unsigned numbers are interoperable. There are no type differences between signed or unsigned values."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:103
+msgid "``AFix`` supports operations without without range expansion. It does this by selecting the aligned maximum and minimum ranges from each of the inputs."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:106
+msgid "``+|`` Add without expansion. ``-|`` Subtract without expansion."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:111
+msgid "Inequality Operations"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:113
+msgid "``AFix`` supports standard inequality operations."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:124
+msgid "Warning: Operations which are out of range at compile time will be optimized out!"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:128
+msgid "Bitshifting"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:130
+msgid "``AFix`` supports decimal and bit shifting"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:132
+msgid "``<<`` Shifts the decimal to the left. Adds to the exponent. ``>>`` Shifts the decimal to the right. Subtracts from the exponent. ``<<|`` Shifts the bits to the left. Adds fractional zeros. ``>>|`` Shifts the bits to the right. Removes fractional bits."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:139
+msgid "Saturation and Rounding"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:141
+msgid "``AFix`` implements saturation and all common rounding methods."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:143
+msgid "Saturation works by saturating the backing value range of an ``AFix`` value. There are multiple helper functions which consider the exponent."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:153
+msgid "``AFix`` rounding modes:"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:170
+msgid "A mathematical example of these rounding modes is better explained here: `Rounding - Wikipedia <https://en.wikipedia.org/wiki/Rounding>`_"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:172
+msgid "All of these modes will result in an ``AFix`` value with 0 exponent. If rounding to a different exponent is required consider shifting or use an assignment with the ``truncated`` tag."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:177
+msgid "Assignment"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:179
+msgid "``AFix`` will automatically check and expand range and precision during assignment. By default, it is an error to assign an ``AFix`` value to another ``AFix`` value with smaller range or precision."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:182
+msgid "The ``.truncated`` function is used to control how assignments to smaller types."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:192
+msgid "``RoundType``:"
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:207
+msgid "The ``saturation`` flag will add logic to saturate to the assigned datatype range."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:209
+msgid "The ``overflow`` flag will allow assignment directly after rounding without range checking."
+msgstr ""
+
+#: ../../SpinalHDL/Data types/AFix.rst:211
+msgid "Rounding is always required when assigning a value with more precision to one with lower precision."
+msgstr ""