Skip to content
Snippets Groups Projects
Select Git revision
  • 976af79f9a2839cfb95c423daa2bf7e0c6dbc74e
  • master default protected
2 results

jami-docs

  • Open with
  • Download source code
  • Your workspaces

      A workspace is a virtual sandbox environment for your code in GitLab.

      No agents available to create workspaces. Please consult Workspaces documentation for troubleshooting.

  • Pierre Nicolas's avatar
    Pierre Nicolas authored
    Change-Id: Ieaa2b6f139ee958fb8aff6726c08d3102fb519b1
    976af79f
    History

    Development

    Transifex

    This project uses Transifex as the translation service, you will need to install Transifex command line tool for managing the translations. You can create a .transifexrc where you can include credentials related to you Transifex account. Reference

    Environment

    Here are the packages for local development:

    • sphinx==6.2.1 (Required by sphinx-rtd-theme 1.2.2)
    • myst-parser==2.0.0
    • sphinx-rtd-theme==1.2.2

    Build HTML

    Extract pot files:

    make gettext 

    Build HTML for the languages specified in a variable named LANGS in the Makefile. Make sure to tx pull the latest translations from Transifex prior building the HTML

    make html 

    Pull/Update Languages

    To pull translated languages from Transifex:

    tx pull -l <lang_code_1>,<lang_code_2> # Specify the language(s) to be pulled
    tx --token <token> pull -l <lang_code_1>,<lang_code_2> # If the token value in `.transifexrc` didn't work
    tx pull -a # all available languages at SFL Transifex
    tx pull -l <lang_code_1>,<lang_code_2> --force # Force updating local '.po' files

    Push Translations/source Files to Transifex

    Pushing files to a remote could be dangerous, read this carefully

    To push source files:

    tx push --branch <your-branch> <project-slug>.<resource-slug>

    To push translations:

    tx push --branch <your-branch> <project-slug>.<resource-slug> -t # -t means only push the translation files

    You can find the project slug and the resource slug at .tx/config. You can also add token before the command push if needed.

    Theme

    This project uses sphinx_rtd_theme as the basic theme. You can find all the HTML files for this theme in the theme folder (e.g. /python3.10/site-packages/sphinx_rtd_theme if installed via PyPI).
    Here are the steps you may take to make changes to the theme:

    1. Find the HTML file that you need to change (sphinx_rtd_theme/layout.html)
    2. Create a file in the folder _template at the root directory with the same name. (_template/layout.html)
    3. Copy the content of the file from step 1 to the file you created in step 2.
    4. Make changes accordingly to the file (_template/layout.html) you created.

    Having a file in _template with the same name makes Sphinx to override the default HTML file in the theme. Making changes to the original HTML files would do the same job but thoses files are not nor supposed to be tracked. You may also create your custom HTML file in _template and include it in other HTML files.

    View Built Pages

    If the HTML files are built successfully, you can use any live server tool to serve the HTML files at your output folder. e.g. Live server extension at VS Code.

    Update Translations

    Always be careful when updating translation via API, TX Client, TM/MT autofill, File upload because it could potentially saved the errors in Transifex even the translation checks will run during the process. To identify the errors, you can filter the translations at Transifex translation editor. Reference

    Important: Some problematic translations won't be interpreted as errors at Transifex but still can cause the build process to fail. For example, the translations in .po files will replace the strings in .rst files respectively during the build. This makes having multiple - stacking in the translation files (.po) a potential issue, it could cause recursion error during the build because - is a special character in .rst files which is treated as a list item if placed at the line start.

    Debugging Tips

    Locate broken files

    You can try to exclude some files during the build process to locate the files that break the build. This can be achieved by adding file patterns in conf.py.

    exclude_patterns = ['out/', 'manual/*.rst']

    Build Logs

    If you want to output the build log of make html to a desired file, go to Makefile at your root directory, find the code block with %: Makefile, then add the -w option like the following:

    @for l in $(LANGS); do \
        $(CMD) -M $@ "$(SRC)" "$(OUT)/$$l" \
        	    -D language="$$l" \
        		-w "log-$$l.log" \ # Write the logs to this file where $$l is the value of l 
        	    -D html_baseurl="https://docs.jami.net/$$l" \
        	    $(OPTS); \
    done