From 6b66025d12d5f18289f32d3617122c892f9a418e Mon Sep 17 00:00:00 2001 From: Omar Al-Ithawi Date: Wed, 28 Feb 2024 20:19:44 +0300 Subject: [PATCH] docs: discourage manual install; advertize pip --- README.rst | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index 387d505..c089f9f 100644 --- a/README.rst +++ b/README.rst @@ -21,15 +21,26 @@ necessary to run any application in English. Installation ------------ -Atlas itself is a bash script, but it can be installed in a couple of -different ways: +Atlas itself is a bash script. It is recommended to install it as a package +to avoid unintentionally installing breaking changes, +while also simplifying the updating process. + +Atlas prerequisites are ``git>=2.20.1`` and ``bash``. + +**Install as a ``pip`` package** + +Install from `PyPI `_ + +.. code:: sh + + pip install openedx-atlas # or add the package to your requirements.txt + +Verify that it is installed via ``atlas --help``. -First, ensure ``git`` is installed and available in ``PATH`` because atlas -relies on it. **Install as an ``npm`` package** -Install from npm: +Install from `npm `_. .. code:: sh @@ -37,18 +48,23 @@ Install from npm: Then add ``node_modules/.bin`` to your ``PATH``. -Verify that is installed via ``atlas --help``. +Verify that it is installed via ``atlas --help``. + + +**Install manually from GitHub releases** -**Install directly from GitHub releases** +This is considered a last resort because of the manual burden of updating +the ``atlas`` executable version or risking introducing breaking +changes to your code. -* Download ``atlas`` from the `latest release `_, or from the `main branch `_: +* Download ``atlas`` from the `latest release `_ or from the `main branch `_: .. code:: sh curl -L https://github.com/openedx/openedx-atlas/releases/latest/download/atlas -o atlas -* Allow execution ``chmod +x atlas`` -* Either add ``atlas`` to your ``PATH``, or run using ``./atlas`` +* Allow execution with ``chmod +x atlas`` +* Either add ``atlas`` to your ``PATH`` or run it using ``./atlas`` Usage -----