From 9c7eed0e27dded7cacbf42cc894ea31447e5a514 Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Thu, 4 Jun 2020 11:21:30 -0700 Subject: [PATCH] Add README.md instructions and test build environment This was created when the website was unavaialble and is part of moving instructions to README.md files as outlined in core-geonetwork/README.md Signed-off-by: Jody Garnett --- .tx/config | 195 +++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 13 ++-- README.md | 87 +++++++++++++++++----- source/conf.py | 5 ++ 4 files changed, 275 insertions(+), 25 deletions(-) diff --git a/.tx/config b/.tx/config index fc971f03..3ed5a1be 100644 --- a/.tx/config +++ b/.tx/config @@ -835,16 +835,19 @@ type = PO file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/harvesting-ogcwxs.po source_file = _build/locale/user-guide/harvesting/harvesting-ogcwxs.pot source_lang = en +type = PO [core-geonetwork.user-guide--index] file_filter = source/locale//LC_MESSAGES/user-guide/index.po source_file = _build/locale/user-guide/index.pot source_lang = en +type = PO [core-geonetwork.user-guide--publishing--restricting-information-to-metadata-sections] file_filter = source/locale//LC_MESSAGES/user-guide/publishing/restricting-information-to-metadata-sections.po source_file = _build/locale/user-guide/publishing/restricting-information-to-metadata-sections.pot source_lang = en +type = PO [core-geonetwork.user-guide--publishing--transfering-privileges] file_filter = source/locale//LC_MESSAGES/user-guide/publishing/transfering-privileges.po @@ -855,149 +858,341 @@ source_lang = en file_filter = source/locale//LC_MESSAGES/user-guide/publishing/index.po source_file = _build/locale/user-guide/publishing/index.pot source_lang = en +type = PO [core-geonetwork.user-guide--publishing--managing-privileges] file_filter = source/locale//LC_MESSAGES/user-guide/publishing/managing-privileges.po source_file = _build/locale/user-guide/publishing/managing-privileges.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--validation] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/validation.po source_file = _build/locale/user-guide/workflow/validation.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--geopublication] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/geopublication.po source_file = _build/locale/user-guide/workflow/geopublication.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--batchupdate-xsl] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/batchupdate-xsl.po source_file = _build/locale/user-guide/workflow/batchupdate-xsl.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--life-cycle] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/life-cycle.po source_file = _build/locale/user-guide/workflow/life-cycle.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--suggestion] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/suggestion.po source_file = _build/locale/user-guide/workflow/suggestion.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--index] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/index.po source_file = _build/locale/user-guide/workflow/index.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--versioning] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/versioning.po source_file = _build/locale/user-guide/workflow/versioning.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--batchupdate-from-admin] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/batchupdate-from-admin.po source_file = _build/locale/user-guide/workflow/batchupdate-from-admin.pot source_lang = en +type = PO [core-geonetwork.user-guide--workflow--batchupdate] file_filter = source/locale//LC_MESSAGES/user-guide/workflow/batchupdate.po source_file = _build/locale/user-guide/workflow/batchupdate.pot source_lang = en +type = PO [core-geonetwork.user-guide--harvesting--harvesting-wfs-features] file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/harvesting-wfs-features.po source_file = _build/locale/user-guide/harvesting/harvesting-wfs-features.pot source_lang = en +type = PO [core-geonetwork.user-guide--harvesting--harvesting-sde] file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/harvesting-sde.po source_file = _build/locale/user-guide/harvesting/harvesting-sde.pot source_lang = en +type = PO [core-geonetwork.user-guide--harvesting--harvesting-z3950] file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/harvesting-z3950.po source_file = _build/locale/user-guide/harvesting/harvesting-z3950.pot source_lang = en +type = PO [core-geonetwork.user-guide--harvesting--harvesting-thredds] file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/harvesting-thredds.po source_file = _build/locale/user-guide/harvesting/harvesting-thredds.pot source_lang = en +type = PO [core-geonetwork.user-guide--harvesting--harvesting-webdav] file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/harvesting-webdav.po source_file = _build/locale/user-guide/harvesting/harvesting-webdav.pot source_lang = en +type = PO [core-geonetwork.user-guide--harvesting--index] file_filter = source/locale//LC_MESSAGES/user-guide/harvesting/index.po source_file = _build/locale/user-guide/harvesting/index.pot source_lang = en +type = PO [core-geonetwork.user-guide--quick-start--index] file_filter = source/locale//LC_MESSAGES/user-guide/quick-start/index.po source_file = _build/locale/user-guide/quick-start/index.pot source_lang = en +type = PO [core-geonetwork.user-guide--tag-information--tagging-with-categories] file_filter = source/locale//LC_MESSAGES/user-guide/tag-information/tagging-with-categories.po source_file = _build/locale/user-guide/tag-information/tagging-with-categories.pot source_lang = en +type = PO [core-geonetwork.user-guide--tag-information--tagging-with-keywords] file_filter = source/locale//LC_MESSAGES/user-guide/tag-information/tagging-with-keywords.po source_file = _build/locale/user-guide/tag-information/tagging-with-keywords.pot source_lang = en +type = PO [core-geonetwork.user-guide--tag-information--index] file_filter = source/locale//LC_MESSAGES/user-guide/tag-information/index.po source_file = _build/locale/user-guide/tag-information/index.pot source_lang = en +type = PO [core-geonetwork.index] file_filter = source/locale//LC_MESSAGES/index.po source_file = _build/locale/index.pot source_lang = en +type = PO [core-geonetwork.administrator-guide--configuring-the-catalog--user-interface-configuration] file_filter = source/locale//LC_MESSAGES/administrator-guide/configuring-the-catalog/user-interface-configuration.po source_file = _build/locale/administrator-guide/configuring-the-catalog/user-interface-configuration.pot source_lang = en +type = PO [core-geonetwork.maintainer-guide--statistics--setup-elasticsearch] file_filter = source/locale//LC_MESSAGES/maintainer-guide/statistics/setup-elasticsearch.po source_file = _build/locale/maintainer-guide/statistics/setup-elasticsearch.pot source_lang = en +type = PO [core-geonetwork.maintainer-guide--statistics--setup-geonetwork] file_filter = source/locale//LC_MESSAGES/maintainer-guide/statistics/setup-geonetwork.po source_file = _build/locale/maintainer-guide/statistics/setup-geonetwork.pot source_lang = en +type = PO [core-geonetwork.maintainer-guide--statistics--index] file_filter = source/locale//LC_MESSAGES/maintainer-guide/statistics/index.po source_file = _build/locale/maintainer-guide/statistics/index.pot source_lang = en +type = PO [core-geonetwork.maintainer-guide--statistics--setup-kibana] file_filter = source/locale//LC_MESSAGES/maintainer-guide/statistics/setup-kibana.po source_file = _build/locale/maintainer-guide/statistics/setup-kibana.pot source_lang = en +type = PO [core-geonetwork.overview--change-log--version-3_4_3] file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.4.3.po source_file = _build/locale/overview/change-log/version-3.4.3.pot source_lang = en +type = PO [core-geonetwork.overview--change-log--version-3_4_2] file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.4.2.po source_file = _build/locale/overview/change-log/version-3.4.2.pot source_lang = en +type = PO [core-geonetwork.overview--change-log--version-3_4_1] file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.4.1.po source_file = _build/locale/overview/change-log/version-3.4.1.pot source_lang = en +type = PO + +[core-geonetwork.administrator-guide--configuring-the-catalog--css-configuration] +file_filter = source/locale//LC_MESSAGES/administrator-guide/configuring-the-catalog/css-configuration.po +source_file = _build/locale/administrator-guide/configuring-the-catalog/css-configuration.pot +source_lang = en +type = PO + +[core-geonetwork.administrator-guide--configuring-the-catalog--portal-configuration] +file_filter = source/locale//LC_MESSAGES/administrator-guide/configuring-the-catalog/portal-configuration.po +source_file = _build/locale/administrator-guide/configuring-the-catalog/portal-configuration.pot +source_lang = en +type = PO + +[core-geonetwork.administrator-guide--managing-metadata-standards--configure-validation] +file_filter = source/locale//LC_MESSAGES/administrator-guide/managing-metadata-standards/configure-validation.po +source_file = _build/locale/administrator-guide/managing-metadata-standards/configure-validation.pot +source_lang = en +type = PO + +[core-geonetwork.administrator-guide--managing-metadata-standards--metadata-identifier] +file_filter = source/locale//LC_MESSAGES/administrator-guide/managing-metadata-standards/metadata-identifier.po +source_file = _build/locale/administrator-guide/managing-metadata-standards/metadata-identifier.pot +source_lang = en +type = PO + +[core-geonetwork.administrator-guide--managing-metadata-standards--standards] +file_filter = source/locale//LC_MESSAGES/administrator-guide/managing-metadata-standards/standards.po +source_file = _build/locale/administrator-guide/managing-metadata-standards/standards.pot +source_lang = en +type = PO + +[core-geonetwork.annexes--standards--dublin-core] +file_filter = source/locale//LC_MESSAGES/annexes/standards/dublin-core.po +source_file = _build/locale/annexes/standards/dublin-core.pot +source_lang = en +type = PO + +[core-geonetwork.annexes--standards--iso19110] +file_filter = source/locale//LC_MESSAGES/annexes/standards/iso19110.po +source_file = _build/locale/annexes/standards/iso19110.pot +source_lang = en +type = PO + +[core-geonetwork.annexes--standards--iso19115-3_2018] +file_filter = source/locale//LC_MESSAGES/annexes/standards/iso19115-3.2018.po +source_file = _build/locale/annexes/standards/iso19115-3.2018.pot +source_lang = en +type = PO + +[core-geonetwork.annexes--standards--iso19139] +file_filter = source/locale//LC_MESSAGES/annexes/standards/iso19139.po +source_file = _build/locale/annexes/standards/iso19139.pot +source_lang = en +type = PO + +[core-geonetwork.api--q-search] +file_filter = source/locale//LC_MESSAGES/api/q-search.po +source_file = _build/locale/api/q-search.pot +source_lang = en +type = PO + +[core-geonetwork.contributing--style-guide] +file_filter = source/locale//LC_MESSAGES/contributing/style-guide.po +source_file = _build/locale/contributing/style-guide.pot +source_lang = en +type = PO + +[core-geonetwork.maintainer-guide--installing--map-print-setup] +file_filter = source/locale//LC_MESSAGES/maintainer-guide/installing/map-print-setup.po +source_file = _build/locale/maintainer-guide/installing/map-print-setup.pot +source_lang = en +type = PO + +[core-geonetwork.maintainer-guide--production-use--index] +file_filter = source/locale//LC_MESSAGES/maintainer-guide/production-use/index.po +source_file = _build/locale/maintainer-guide/production-use/index.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_10_0] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.10.0.po +source_file = _build/locale/overview/change-log/version-3.10.0.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_10_1] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.10.1.po +source_file = _build/locale/overview/change-log/version-3.10.1.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_10_2] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.10.2.po +source_file = _build/locale/overview/change-log/version-3.10.2.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_4_4] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.4.4.po +source_file = _build/locale/overview/change-log/version-3.4.4.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_6_0] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.6.0.po +source_file = _build/locale/overview/change-log/version-3.6.0.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_8_0] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.8.0.po +source_file = _build/locale/overview/change-log/version-3.8.0.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_8_1] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.8.1.po +source_file = _build/locale/overview/change-log/version-3.8.1.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_8_2] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.8.2.po +source_file = _build/locale/overview/change-log/version-3.8.2.pot +source_lang = en +type = PO + +[core-geonetwork.overview--change-log--version-3_8_3] +file_filter = source/locale//LC_MESSAGES/overview/change-log/version-3.8.3.po +source_file = _build/locale/overview/change-log/version-3.8.3.pot +source_lang = en +type = PO + +[core-geonetwork.user-guide--associating-resources--doi] +file_filter = source/locale//LC_MESSAGES/user-guide/associating-resources/doi.po +source_file = _build/locale/user-guide/associating-resources/doi.pot +source_lang = en +type = PO + +[core-geonetwork.user-guide--describing-information--inspire-editing] +file_filter = source/locale//LC_MESSAGES/user-guide/describing-information/inspire-editing.po +source_file = _build/locale/user-guide/describing-information/inspire-editing.pot +source_lang = en +type = PO + +[core-geonetwork.user-guide--map--index] +file_filter = source/locale//LC_MESSAGES/user-guide/map/index.po +source_file = _build/locale/user-guide/map/index.pot +source_lang = en +type = PO + +[core-geonetwork.user-guide--publishing--transferring-privileges] +file_filter = source/locale//LC_MESSAGES/user-guide/publishing/transferring-privileges.po +source_file = _build/locale/user-guide/publishing/transferring-privileges.pot +source_lang = en +type = PO + +[core-geonetwork.user-guide--workflow--batchediting] +file_filter = source/locale//LC_MESSAGES/user-guide/workflow/batchediting.po +source_file = _build/locale/user-guide/workflow/batchediting.pot +source_lang = en +type = PO diff --git a/Makefile b/Makefile index b2791e5e..5a111cb5 100755 --- a/Makefile +++ b/Makefile @@ -8,6 +8,7 @@ SPHINXOPTS = # used by html_languages to specify $$lang SPHINXBUILD = sphinx-build PAPER = BUILDDIR = target +PUBLISH = _build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) @@ -17,7 +18,7 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) -j auto --no-color -q +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -j auto $(SRCDIR) --no-color -q # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) @@ -30,7 +31,7 @@ help: @echo " html_all_languages build html documentation for all languages " @echo " html_languages build html docs for LANGS environmental variable" @echo " html_eng build html documentation for english" - @echo " update_translations Pushing strings to transifex" + @echo " update_translations Pushing strings to transifex (via _build folder)" @echo "Along with traditional sphinx targets:" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @@ -72,10 +73,12 @@ html_eng: @echo "Building documentation in html for all languages" set -e; for lang in "en"; do echo "Building language $$lang" && make html -e SPHINXOPTS="-D language='$$lang'" -e "BUILDDIR='target/doc/$$lang' -d $(BUILDDIR)/doctrees"; done -update_translations: +update_translations: @echo "Pushing strings to transifex" - make gettext - set -e; sphinx-intl update-txconfig-resources --pot-dir $(BUILDDIR)/locale --transifex-project-name core-geonetwork; + @echo "Step 1: Obtain tanslations using gettext builder" + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(PUBLISH)/locale + @echo "Step 2: Publish to ${PUBLISH}/local folder" + set -e; sphinx-intl update-txconfig-resources --pot-dir $(PUBLISH)/locale --transifex-project-name core-geonetwork; set -e; tx push -s html: diff --git a/README.md b/README.md index 3eaa1a65..3929ae93 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,14 @@ # Project documentation module -Documentation for GeoNetwork Opensource available via https://geonetwork-opensource.org. +Documentation for GeoNetwork Opensource available via [geonetwork-opensource.org](https://geonetwork-opensource.org). This manual is included in each build in the `docs` folder as a git submodule. -This documentation is supports open access using a [Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)](LICENSE.md). +* `_build`: contains reference `pot` files used by Transifex for translation. +* `source/config.py`: sphinx build configuration settings +* `theme`: geonetwork documentation theme + + +GeoNetwork documentation is supports open access using a [Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)](LICENSE.md). ![GeoNetwork Logo](source/_static/GN3.png "GeoNetwork") @@ -19,12 +24,64 @@ To quickly build the english docs: make html_eng ``` +# Translations + A build of the documentation (defaulting to English and French): ``` mvn package ``` +## Before you start + +Install `tx` client: + +#. The maven build above makes use of the transifex command line client :command:`tx`: + + * https://docs.transifex.com/client/introduction + + Intall: `pip install transifex-client` + +#. Generate an API key: https://www.transifex.com/user/settings/api/ + +#. To install API key: + + * Either create manually the file `~/.transifexrc` including your API token: + + ``` + [https://www.transifex.com] + api_hostname = https://api.transifex.com + hostname = https://www.transifex.com + password = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + username = api + ``` + + * Or run `tx` once interactively to install the API key: + + ``` + tx pull --language='fr' + [?] Enter your api token: + ``` + +Install `sphinx-intl`: + +#. Manging translations requires :command:`sphinx-intl` tool: + + * http://sphinx-intl.rtfd.io + +#. Install: `pip install sphinx-intl` + +Recommend `python-levenshtein`: + +#. Speed up calculating edit-distance when cross comparing changes using `sphinx-intl`: + + * https://github.com/ztane/python-Levenshtein/ + +#. Install: `pip install python-levenshtein` + + +## Update Translations from Transefex + The `latest` maven profile updates the translations from Transifex (this will take some time). ``` @@ -48,29 +105,19 @@ A subset of languages (for example: English, French and Spanish): mvn package -Platest -Dlangs='"en" "fr" "es"' -Dtranslations='en,fr,es' ``` -# Before you start +## Publish new documentation for translation -The maven build above makes use of the transifex command line client `tx`: +To update the `pot` files in `_build/locale`: -* https://docs.transifex.com/client/introduction - -Prior to use you will need to generate and API key: - -* https://www.transifex.com/user/settings/api/ +``` +make update_translations +``` -If you have never used `tx` before you will need to run it once interactively to install the API key: +And commit the change: ``` -tx pull --language='fr' -[?] Enter your api token: +git add _build/locale +git commit -m "updated translations" ``` -Another option is to generate manually the file `~/.transifexrc` including your API token: -``` -[https://www.transifex.com] -api_hostname = https://api.transifex.com -hostname = https://www.transifex.com -password = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -username = api -``` diff --git a/source/conf.py b/source/conf.py index 1a2306be..2fd2876a 100644 --- a/source/conf.py +++ b/source/conf.py @@ -80,6 +80,11 @@ locale_dirs = ['locale/'] # path is example but recommended. gettext_compact = False # optional. +# Generates uuid information for version tracking in message catalogs +# Calculate similarity between new msgids and previously saved old msgids. +# recommend: pip3 install python-levenshtein +gettext_uuid = True + # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = ''