Merge pull request #236 from AequilibraE/develop

0.9.3 release

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-FROM qgis/qgis:release-3_22
+FROM qgis/qgis:release-3_28
 
 # [Optional] Uncomment this section to install additional OS packages.
 RUN apt update -y && apt install -y pandoc zip

.github/transifex.yml

@@ -0,0 +1,15 @@
+filters:
+  - filter_type: file
+    file_format: QT
+    source_language: en
+    source_file: qaequilibrae/i18n/qaequilibrae.ts
+    translation_files_expression: 'qaequilibrae/i18n/qaequilibrae_<lang>.ts'
+settings:
+  language_mapping:
+    fr: fr_FR
+    pt: pt_BR
+    en: en_US
+    de: de
+    it: it
+    es: es
+    zh: zh_CN

.github/workflows/DevWorkflow.yml

@@ -20,30 +20,12 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python3 -m pip install -r requirements.txt
-          python3 -m pip install -r requirements-dev.txt
+          python3 -m pip install -r qaequilibrae/requirements.txt
+          python3 -m pip install -r ci/requirements-dev.txt
           python3 -m pip install numpy --upgrade
 
       - name: Run tests
         run: |
           export QT_QPA_PLATFORM=offscreen
           pwd
-          python3 -m pytest test
-
-  packaging:
-#    needs: linting
-    runs-on: ubuntu-latest
-    steps:
-      - name: Build artifact
-        run: |
-          rm -rf ./tests ./test ./docs .git .devcontainer .github
-          mkdir -p /tmp/artifacts
-          cd ..
-          zip -r /tmp/artifacts/QAequilibraE.zip ./qaequilibrae
-
-      - name: Stores artifacts along with the workflow result
-        uses: actions/upload-artifact@v3
-        with:
-          name: library
-          path: /tmp/artifacts/*.zip
-          if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn`
+          python3 -m pytest test -v --tb=short

.github/workflows/documentation.yml

@@ -21,7 +21,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
+        pip install -r qaequilibrae/requirements.txt
         pip install -r docs/requirements-docs.txt
 
     - name: Build documentation

.github/workflows/translation.yml

@@ -0,0 +1,103 @@
+name: translate & package
+
+env:
+  PLUGIN_VERSION: $(python qaequilibrae/get_version.py)
+  PROJECT_FOLDER: "qaequilibrae"
+  CURRENT_BRANCH: $(git branch --show-current)
+
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+  release:
+
+jobs:
+  translation:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 4
+    steps:
+    - uses: actions/checkout@v3
+      with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+
+    - name: Install packages
+      run: |
+        sudo apt-get update
+        sudo apt install qttools5-dev-tools
+        python -m pip install --upgrade pip
+        python -m pip install -r ci/packaging.txt
+    
+    - name: Create translatable files
+      if: ${{(github.ref == 'refs/heads/develop') && (github.event_name == 'push')}}
+      run: |
+        python qaequilibrae/i18n/create_pro_file.py
+        pylupdate5 qaequilibrae/i18n/qaequilibrae.pro
+
+    - name: Check if there are modifications in the translatable files
+      if: ${{(github.ref == 'refs/heads/develop') && (github.event_name == 'push')}}
+      run: |
+        git fetch --no-tags --depth=1 origin ${{ env.CURRENT_BRANCH }}
+        files_created=$(git ls-files --others --exclude-standard)
+        files_changed=$(git diff --name-only)
+
+        if echo "${files_changed}" | grep --quiet "qaequilibrae/i18n/qaequilibrae.ts"; then
+          echo ".ts file was modified!"
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+          git add qaequilibrae/i18n/qaequilibrae.ts
+          git commit -a -m "Adds translatable files"
+          git push origin HEAD:refs/heads/${{ env.CURRENT_BRANCH }}
+        
+        elif echo "${files_created}" | grep --quiet "qaequilibrae/i18n/qaequilibrae.ts"; then
+          echo ".ts file was created!"
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+          git add qaequilibrae/i18n/qaequilibrae.ts
+          git commit -a -m "Adds translatable files"
+          git push origin HEAD:refs/heads/${{ env.CURRENT_BRANCH }}
+
+        else
+          echo ".ts file wasn't modified."
+        fi
+
+    - name: Compile translations if they exist
+      run: |
+        cd qaequilibrae/i18n
+        translatable_files=$(ls)
+        cd ../..
+        if echo "$translatable_files" | grep "qaequilibrae_.*\.ts"; then
+          echo "Translatable files found"
+          lrelease ${{ env.PROJECT_FOLDER }}/i18n/qaequilibrae_*.ts
+          sed -i "s|^*.qm.*| |" .gitignore
+          git add ${{ env.PROJECT_FOLDER }}/
+        else
+          echo "No translatable files found"
+        fi
+  
+    - name: Build the package
+      run: qgis-plugin-ci package ${{ env.PLUGIN_VERSION }} -c
+
+    - name: Download artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: qaequilibrae
+        path: /home/runner/work/qaequilibrae/qaequilibrae/*.zip
+        if-no-files-found: warn
+
+    # - name: Deploy plugin
+    #   if: ${{ (github.event_name == 'release')}}
+    #   run: >-
+    #     qgis-plugin-ci
+    #     release ${GITHUB_REF/refs\/tags\//}
+    #     --github-token ${{ secrets.GITHUB_TOKEN }}
+    #     --osgeo-username ${{ secrets.QGIS_PLUGIN_REPO_USER }}
+    #     --osgeo-password ${{ secrets.QGIS_PLUGIN_REPO_PASSWORD }}

.gitignore

@@ -56,4 +56,8 @@ aequilibrae/paths/parameters.html
 aequilibrae/paths/build/*
 
 
-# End of https://www.gitignore.io/api/jetbrains
+# End of https://www.gitignore.io/api/jetbrains
+# qgis-plugin-ci
+# qequilibrae.zip
+# qaequilibrae.*.zip
+

.qgis-plugin-ci

@@ -0,0 +1,3 @@
+plugin_path: qaequilibrae
+github_organization_slug: aequilibrae
+project_slug: qaequilibrae

ci/packaging.txt

@@ -0,0 +1 @@
+qgis-plugin-ci==2.7.2

docs/source/conf.py

@@ -27,7 +27,7 @@
 
 # The short X.Y.Z version
 
-a = open("../../metadata.txt", "r")
+a = open("../../qaequilibrae/metadata.txt", "r")
 for line in a.readlines():
     if "version" in line.rstrip():
         version = line.rstrip()[8:]

docs/source/development/softwaredevelopment.rst

@@ -100,14 +100,43 @@ Imports
 
     import numpy as np
 
+Translatable Strings
+~~~~~~~~~~~~~~~~~~~~
+
+In case you are adding and/or changing any piece of QAequilibraE's code with translatable strings,
+which are those strings we see in the widget windows, please make sure to indicate they are translatable by
+importing the `tr` function. This shall guarantee you that the string will be compiled into our
+future translations.
+
+::
+
+    from qaequilibrae.i18n.translator import tr
+
+    # Indicates that the message "You need at least three centroids to route. " will be
+    # set for translation.
+    qgis.utils.iface.messageBar().pushMessage(tr("You need at least three centroids to route. "), "", level=3)
+
+    # In case you have to insert any text into a string, the best way is to use string format
+    self.error = tr("ID {} is non unique in your selected field").format(str(i_d))
+
+As for June 2023, QAequilibraE's translations are all hosted in 
+`Transifex <https://explore.transifex.com/aequilibrae/qaequilibrae/>`_. Currently, we are targeting translations
+in Brazilian Portuguese, Chinese, French, German, Italian, and Spanish. If you want to contribute to QAequilibraE 
+by translating the plugin to other languages, please let us know in our 
+`AequilibraE Google Group <https://groups.google.com/forum/#!forum/aequilibrae>`_,
+so we can add your language to our translation pool!
+
+In the :ref:`plugin-translation`page, you can find more information on creating you account and
+start translating QAequilibraE.
+
 Contributing to AequilibraE for QGIS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 GitHub has a nice visual explanation on how collaboration is done `GitHub Flow
 <https://guides.github.com/introduction/flow>`_. (For us,) The most important points there are:
 
 * The master branch contains the latest working/release version of AequilibraE
-* Work is done in an issue/feature branch (or a fork) and then pushed to a new brach
+* Work is done in an issue/feature branch (or a fork) and then pushed to a new branch
 * Automated testing is run using Github Actions. All tests must pass:
 
   * Unit testing
@@ -167,7 +196,7 @@ Documentation
 
 All the AequilibraE documentation is (unfortunately) written in `reStructuredText
 <http://docutils.sourceforge.net/rst.html>`_ and built with `Sphinx <http://www.sphinx-doc.org/en/stable/>`_.
-Although Restructured Text is often unecessarily convoluted to write, Sphinx is capable of converting it to standard-
+Although Restructured Text is often unnecessarily convoluted to write, Sphinx is capable of converting it to standard-
 looking html pages, while also bringing the docstring documentation along for the ride.
 
 To build the documentation, first make sure the required packages are installed::

docs/source/development/transifex.rst

@@ -0,0 +1,85 @@
+.. _plugin-translation:
+
+Plug-in translation
+===================
+
+In this section, we briefly explain how you can get your Transifex account and how to start 
+contributing to QAquilibraE translation.
+
+Creating account
+~~~~~~~~~~~~~~~~
+
+To translate QAequilibraE's QGIS plug-in, we use Transifex, a web-based platform that
+hosts translations. Before joining our project, you must create an account. Direct yourself
+to `Transifex login page <https://app.transifex.com/signin/?next=/home/>`_ and follow the
+instructions. The process is straightforward and does not take a lot of time.
+
+After creating your account, direct yourself to `team's page 
+<https://explore.transifex.com/aequilibrae/qaequilibrae/>`_ and request your
+access to the project. Approving your request might take a couple of days, so don't worry.
+
+.. image:: ../images/tx_project_1.png
+    :width: 479
+    :align: center
+    :alt: ask-to-join-tx-project
+
+You'll be redirected to this page to enter your translation languages of preference.
+
+.. image:: ../images/tx_project_2.png
+    :width: 479
+    :align: center
+    :alt: select-tx-pref-languages
+
+As soon as you have your request approved, you can log in once more in Transifex and begin
+translating.
+
+.. image:: ../images/tx_project_3.png
+    :width: 479
+    :align: center
+    :alt: tx-waiting-for-approval
+
+
+Translating into your language
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your project screen should look like the one in the figure below. In this example, 
+we only have Brazilian Portuguese and French as translation options. 
+
+.. image:: ../images/tx_project_4.png
+    :width: 479
+    :align: center
+    :alt: tx-project-page
+
+If you feel comfortable translating into any of these idioms, just drag your cursor to the 
+right side of each translatable idiom and click on the **Translate** button. You'll be redirected
+to a new page.
+
+.. image:: ../images/tx_project_6.png
+    :width: 479
+    :align: center
+    :alt: tx-project-page
+
+You can check the translation status in the left column (*Text*), where the green buttons indicate
+that there is an existing translation for that string. You can insert their
+translation in the box and save it for all strings If your string happens to appear multiple times,
+Transifex will give you translation suggestions, that can match whatever you want to translate.
+This can spare you some time.
+
+When you finish your work, direct yourself to the **Unreviewed** field, to check
+all strings you have translated. Here's your opportunity to look for typos or incorrect translations.
+
+For more information, we strongly encourage you to check Transifex official documentation in their
+website.
+
+Suggesting a new translation language
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your language is unavailable and you want to contribute, you can request it directly to
+the AequilibraE Team! In your project screen, look for the **Request a language** button on the page.
+Select your language and create a request. As soon as we can, we'll approve the creation of the
+language, and you can start translating!
+
+.. image:: ../images/tx_project_5.png
+    :width: 479
+    :align: center
+    :alt: tx-request-a-language