Skip to content

Commit

Permalink
feat: document atlas language and directory map params
Browse files Browse the repository at this point in the history 
document new params:

 - --dry-run
 - --languages
 - --directory arg replacement

Refs: FC-0012 OEP-58
  • Loading branch information
@OmarIthawi
OmarIthawi committed Apr 5, 2023
1 parent 307af2d commit c75269d
Showing 1 changed file with 128 additions and 27 deletions.
155 changes: 128 additions & 27 deletions atlas
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,74 @@
# getoptions generates code that fails this check, so we need to disable it
# shellcheck disable=SC2004


# @getoptions
parser_definition() {
setup REST help:usage -- \
"Atlas is a CLI tool that has essentially one command: \`atlas pull\`\n \nAtlas defaults to using a configuration file named \`atlas.yml\` placed\nin the root directory. Configuration file:\n \npull:\n branch: <branch-name>\n directory <directory-name>\n repository: <organization-name>/<repository-name>\n \nAtlas can also use a configuration file in a different path using the \`--config\` flag\nafter \`atlas\`: \`atlas pull --config config.yml\`.\n \nAtlas can also be used without a configuration file by using the flags below after\n\`atlas pull\`.\n \n\`-b\` or \`--branch\`\n\`-r\` or \`--repository\`\n\`-d\` or \`--directory\`" ''
_ATLAS_USAGE_HELP="Atlas is a CLI tool that has essentially one command: \`atlas pull\`
Configuration file:
Atlas defaults to using a configuration file named \`atlas.yml\` placed
in the root directory. Configuration file:
pull:
repository: <organization-name>/<repository-name>
branch: <branch-name>
directory: <repo-directory-name>:<local-dir-name>
languages: ar,de,fr_CA
Atlas can also use a configuration file in a different path using the \`--config\` flag
after \`atlas\`: \`atlas pull --config config.yml\`.
Atlas can also be used without a configuration file by using the flags below after
\`atlas pull\`.
Arguments:
\`-r\` or \`--repository\`:
A repository GitHub repo slug defaults to 'openedx/openedx-translations'.
\`-b\` or \`--branch\`:
The git branch defaults to 'main'.
\`-d\` or \`--directory\`
A comma-separated (or space-separated) of directory map pairs. Each map pair represents a
directory to copy translations from the repo into which directory in the local working tree:
--directory=learning-app/messages:learning-messages,footer/messages:footer-messages
This is inspired by \`docker --volume from_dir:to_dir\` mounting syntax.
\`-l\` or \`--languages\`
A comma-separated (or space-separated) list of languages to pattern match files against defaults to '*' for
all languages.
---languages=fr_CA,ar,es_419 will match both directories named 'es_419' and files named 'es_419.json'
Example:
$ cd src/i18n/messages
$ atlas pull --languages='fr_CA,ar,es_419' \
--directory='translations/frontend-app-learning/src/i18n/messages:frontend-app-learning translations/frontend-component-header/src/i18n/messages:frontend-component-header'
Will result in the following tree:
├── frontend-app-learning
│ ├── ar.json
│ ├── es_419.json
│ └── fr_CA.json
└── frontend-component-header
├── ar.json
├── es_419.json
└── fr_CA.json
More examples are available in the repository docs: https://github.com/openedx/openedx-translations .
"

setup REST help:usage -- "${_ATLAS_USAGE_HELP}" ''
msg -- '' 'Commands:'
cmd pull -- "pull"
disp :usage -h --help
disp :usage -h --help
}

parser_definition_pull() {
Expand All @@ -18,10 +79,10 @@ parser_definition_pull() {
param CONFIG --config -- "path to alternative atlas.yaml configuration file"
param BRANCH -b --branch -- "A branch of translation files"
param REPOSITORY -r --repository -- "The repository containing translation files"
param DIRECTORY -d --directory -- "Directory (name of the repository) containing translations to be downloaded"
param DIRECTORY -d --directory -- "List of directories to map FROM_REPO1:TO_LOCAL1,FROM_REPO2:TO_LOCAL2,..."
flag VERBOSE -v --verbose -- "verbose output to terminal"
flag SILENT -s --silent -- "no output to terminal"
disp :usage_pull -h --help
disp :usage_pull -h --help
}
# @end

Expand Down Expand Up @@ -79,24 +140,64 @@ parse() {
usage() {
cat<<'GETOPTIONSHERE'
Atlas is a CLI tool that has essentially one command: `atlas pull`
Atlas defaults to using a configuration file named `atlas.yml` placed
in the root directory. Configuration file:
pull:
branch: <branch-name>
directory <directory-name>
repository: <organization-name>/<repository-name>
Atlas can also use a configuration file in a different path using the `--config` flag
after `atlas`: `atlas pull --config config.yml`.
Atlas can also be used without a configuration file by using the flags below after
`atlas pull`.
`-b` or `--branch`
`-r` or `--repository`
`-d` or `--directory`
Configuration file:
Atlas defaults to using a configuration file named `atlas.yml` placed
in the root directory. Configuration file:
pull:
repository: <organization-name>/<repository-name>
branch: <branch-name>
directory: <repo-directory-name>:<local-dir-name>
languages: ar,de,fr_CA
Atlas can also use a configuration file in a different path using the `--config` flag
after `atlas`: `atlas pull --config config.yml`.
Atlas can also be used without a configuration file by using the flags below after
`atlas pull`.
Arguments:
`-r` or `--repository`:
A repository GitHub repo slug defaults to 'openedx/openedx-translations'.
`-b` or `--branch`:
The git branch defaults to 'main'.
`-d` or `--directory`
A comma-separated (or space-separated) of directory map pairs. Each map pair represents a
directory to copy translations from the repo into which directory in the local working tree:
--directory=learning-app/messages:learning-messages,footer/messages:footer-messages
This is inspired by `docker --volume from_dir:to_dir` mounting syntax.
`-l` or `--languages`
A comma-separated (or space-separated) list of languages to pattern match files against defaults to '*' for
all languages.
---languages=fr_CA,ar,es_419 will match both directories named 'es_419' and files named 'es_419.json'
Example:
$ cd src/i18n/messages
$ atlas pull --languages='fr_CA,ar,es_419' --directory='translations/frontend-app-learning/src/i18n/messages:frontend-app-learning translations/frontend-component-header/src/i18n/messages:frontend-component-header'
Will result in the following tree:
├── frontend-app-learning
│ ├── ar.json
│ ├── es_419.json
│ └── fr_CA.json
└── frontend-component-header
├── ar.json
├── es_419.json
└── fr_CA.json
More examples are available in the repository docs: https://github.com/openedx/openedx-translations .
Commands:
Expand Down Expand Up @@ -198,7 +299,7 @@ Options:
--config CONFIG path to alternative atlas.yaml configuration file
-b, --branch BRANCH A branch of translation files
-r, --repository REPOSITORY The repository containing translation files
-d, --directory DIRECTORY Directory (name of the repository) containing translations to be downloaded
-d, --directory DIRECTORY List of directories to map FROM_REPO1:TO_LOCAL1,FROM_REPO2:TO_LOCAL2,...
-v, --verbose verbose output to terminal
-s, --silent no output to terminal
-h, --help
Expand Down Expand Up @@ -300,7 +401,7 @@ pull_translations() {
else
git remote add -f origin "$remote_url"
fi

# finished "Creating a temporary Git repository to pull translations into <temp dir>..." step
if [ -z "$SILENT" ];
then
Expand Down Expand Up @@ -382,10 +483,10 @@ if [ $# -gt 0 ]; then
then
display_pull_params
fi
# allow mocking pull_translations
# allow mocking pull_translations
__ begin_pull_translations_mock __
pull_translations
__ end_pull_translations_mock __
__ end_pull_translations_mock __
;;
--) # no subcommand, arguments only
esac
Expand Down

0 comments on commit c75269d

Please sign in to comment.