docs: update README with atlas --help (#28)

This helps engineers to understand the project at a glance. This contribution is part of the [FC-0012 project](https://openedx.atlassian.net/l/cp/XGS0iCcQ) which is sparked by the [Translation Infrastructure update OEP-58](https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0058-arch-translations-management.html#specification).
openedx · Aug 9, 2023 · c68169c · c68169c
1 parent 18eb0cc
commit c68169c
Show file tree

Hide file tree

Showing 6 changed files with 163 additions and 53 deletions.
diff --git a/.gitignore b/.gitignore
@@ -31,7 +31,7 @@ pip-log.txt
 .tox
 coverage.xml
 htmlcov/
-
+README.rst.backup
 
 
 # The Silver Searcher

diff --git a/Makefile b/Makefile
@@ -26,3 +26,6 @@ integration_tests: ## automated testing using shellspec: faster `git` integratio
 
 test: ## automated testing using shellspec: run all tests
 	shellspec
+
+atlas_help_to_readme: gengetoptions ## Updates the `atlas --help` section of the README.rst file
+	python3 scripts/atlas_help_to_readme.py
diff --git a/README.rst b/README.rst
@@ -34,27 +34,84 @@ Installing Locally
 Usage
 -----
 
-Atlas is a CLI tool that has essentially one command: ``atlas pull``
+The help message below is copied from both ``atlas --help``. It's updated
+regularly and useful to understand ``atlas`` at a glance.
 
-Atlas defaults to using a configuration file named ``atlas.yml`` placed
-in the root directory. Configuration file:
+.. code::
 
-.. code:: yaml
+    Atlas is a CLI tool that has essentially one command: `atlas pull`
 
-    pull:
-      branch: <branch-name>
-      directory: <directory-name>
-      repository: <organization-name>/<repository-name>
+    Configuration file:
 
-Atlas can also use a configuration file in a different path using the ``--config`` flag
-after ``atlas``: ``atlas pull --config config.yml``.
+        Atlas defaults to using a configuration file named `atlas.yml` placed
+        in the root directory. Configuration file:
 
-Atlas can also be used without a configuration file by using the flags below after
-``atlas pull``.
+        pull:
+          repository: <organization-name>/<repository-name>
+          branch: <branch-name>
+          directory: <repo-directory-name>:<local-dir-name> ...
+          filter: <pattern> ...
 
-``-b`` or ``--branch``
-``-r`` or ``--repository``
-``-d`` or ``--directory``
+        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`.
+
+    Positional arguments DIRECTORY MAPPINGS ...
+
+       One or more directory map pair separated by a colon (:) e.g. FROM_DIR:TO_DIR.
+
+       The first directory (FROM_DIR) represents a directory in the git repository.
+       The second directory (TO_DIR) represents a local directory to copy files to.
+
+       At least one directory pair is required:
+
+         $ atlas pull frontend-app-learning/messages:learning-app frontend-lib-test/messages:test-lib
+
+       This syntax is inspired by the `docker --volume from_dir:to_dir` mounting syntax.
+
+    Options:
+
+        `-r` or `--repository`:
+            slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
+
+        `-b` or `--branch`:
+            Branch to pull from. Defaults to 'main'
+
+        `-f` or `--filter`:
+           A comma-separated (or space-separated) list of patterns match files and sub-directories.
+           This is mainly useful to filter specific languages to download.
+
+           The same filter is applied to all DIRECTORY MAPPINGS arguments.
+
+           `--filter=fr_CA,ar,es_419` will match both directories named 'es_419' and
+           files named 'es_419.json' among others
+
+    Example:
+
+        $ cd frontend-app-learning/src/i18n/messages
+        $ atlas pull --filter=fr_CA,ar,es_419 \
+                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
+
+
+
+    Commands:
+      pull      pull
+      -h, --help                  
+          --version               
 
 Running Automated Tests Locally
 -------------------------------
@@ -71,10 +128,25 @@ Running Automated Tests Locally
 * ``make performance_tests``:  run performance tests which pulls from GitHub.com/openedx
 * ``make unit_tests``:  run fast unit tests without external dependency
 
-Documentation
--------------
+Usage Examples
+--------------
+
+There's a couple of patterns that are useful to imitate when using Atlas
+depending on the use case. ``atlas pull`` is most commonly implemented in
+``Makefile``, however it can be also used in ``Dockerfile`` builds or any
+other automation tool.
+
+Python Applications
+*******************
+
+TBD
+
+
+Micro-frontends
+***************
+
+TBD
 
-TODO
 
 Releasing a New Version
 -----------------------

diff --git a/atlas b/atlas
@@ -38,24 +38,24 @@ Positional arguments DIRECTORY MAPPINGS ...
 
      $ atlas pull frontend-app-learning/messages:learning-app frontend-lib-test/messages:test-lib
 
-   This syntax is inspired by \`docker --volume from_dir:to_dir\` mounting syntax.
+   This syntax is inspired by the \`docker --volume from_dir:to_dir\` mounting syntax.
 
 Options:
 
     \`-r\` or \`--repository\`:
-        A repository GitHub repo slug defaults to 'openedx/openedx-translations'.
+        slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
 
     \`-b\` or \`--branch\`:
-        The git branch defaults to 'main'.
+        Branch to pull from. Defaults to 'main'
 
-    \`-f\` or \`--filter\`
+    \`-f\` or \`--filter\`:
        A comma-separated (or space-separated) list of patterns match files and sub-directories.
        This is mainly useful to filter specific languages to download.
 
        The same filter is applied to all DIRECTORY MAPPINGS arguments.
 
-          --filter=fr_CA,ar,es_419 will match both directories named 'es_419' and files named 'es_419.json'
-                                   among others
+       \`--filter=fr_CA,ar,es_419\` will match both directories named 'es_419' and
+       files named 'es_419.json' among others
 
 Example:
 
@@ -64,18 +64,16 @@ Example:
             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:
+    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 .
+      ├── frontend-app-learning
+      │   ├── ar.json
+      │   ├── es_419.json
+      │   └── fr_CA.json
+      └── frontend-component-header
+          ├── ar.json
+          ├── es_419.json
+          └── fr_CA.json
 "
 
 	setup       REST help:usage -- "${_ATLAS_USAGE_HELP}" ''
@@ -185,24 +183,24 @@ Positional arguments DIRECTORY MAPPINGS ...
 
      $ atlas pull frontend-app-learning/messages:learning-app frontend-lib-test/messages:test-lib
 
-   This syntax is inspired by `docker --volume from_dir:to_dir` mounting syntax.
+   This syntax is inspired by the `docker --volume from_dir:to_dir` mounting syntax.
 
 Options:
 
     `-r` or `--repository`:
-        A repository GitHub repo slug defaults to 'openedx/openedx-translations'.
+        slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
 
     `-b` or `--branch`:
-        The git branch defaults to 'main'.
+        Branch to pull from. Defaults to 'main'
 
-    `-f` or `--filter`
+    `-f` or `--filter`:
        A comma-separated (or space-separated) list of patterns match files and sub-directories.
        This is mainly useful to filter specific languages to download.
 
        The same filter is applied to all DIRECTORY MAPPINGS arguments.
 
-          --filter=fr_CA,ar,es_419 will match both directories named 'es_419' and files named 'es_419.json'
-                                   among others
+       `--filter=fr_CA,ar,es_419` will match both directories named 'es_419' and
+       files named 'es_419.json' among others
 
 Example:
 
@@ -211,18 +209,16 @@ Example:
             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
+    Will result in the following tree:
 
-More examples are available in the repository docs: https://github.com/openedx/openedx-translations .
+      ├── frontend-app-learning
+      │   ├── ar.json
+      │   ├── es_419.json
+      │   └── fr_CA.json
+      └── frontend-component-header
+          ├── ar.json
+          ├── es_419.json
+          └── fr_CA.json
 
 
 

diff --git a/scripts/atlas_help_to_readme.py b/scripts/atlas_help_to_readme.py
@@ -0,0 +1,23 @@
+"""
+Updates the `atlas --help` section of the README.rst file.
+"""
+
+import re
+import subprocess
+import textwrap  # Available in Python 3.3+
+
+
+with open('README.rst', encoding='utf-8') as readme_file_r:
+    readme = readme_file_r.read()
+    help_message = subprocess.check_output(['./atlas', '--help']).decode('utf-8')
+    help_message_indented = textwrap.indent(help_message, '    ')  # Ensure it appears as a code-block in the README
+
+    updated_readme = re.sub(
+        r' {4}Atlas is a CLI tool that has essentially.*Running Automated Tests Locally',
+        '{msg}\nRunning Automated Tests Locally'.format(msg=help_message_indented),
+        readme,
+        flags=re.DOTALL,
+    )
+
+with open('README.rst', 'w', encoding='utf-8') as readme_file_w:
+    readme_file_w.write(updated_readme)
diff --git a/spec/readme_help_spec.sh b/spec/readme_help_spec.sh
@@ -0,0 +1,16 @@
+# requires getoptions to be installed
+# installing getoptions locally: https://github.com/ko1nksm/getoptions/#installation
+verify_help_section() {
+  cp README.rst README.rst.backup
+  make -s atlas_help_to_readme
+  diff --report-identical-files README.rst README.rst.backup
+  rm README.rst
+  mv README.rst.backup README.rst
+}
+
+Describe 'atlas help section'
+  It 'has run "make atlas_help_to_readme"'
+    When call verify_help_section
+    The output should equal "Files README.rst and README.rst.backup are identical"
+  End
+End