diff --git a/README.md b/README.md index ef905a0..51b44b2 100644 --- a/README.md +++ b/README.md @@ -19,109 +19,66 @@ You can ## INSTALLATION INSTRUCTIONS -Basie can run on -python <= 3.11 +### Preliminary information +Basie can run on python >= 3.8 +We **strongly** recommend installing `basie` in a virtual environment, using [`conda`](https://www.anaconda.com/download/), +[`venv`](https://docs.python.org/3/library/venv.html), or equivalent systems. This will avoid conflicts with system libraries or +Python versions installed as part of other packages (e.g. CASA, see below in the Known Issues). -Before installing the package make sure you download and extract the package -archive at -http://github.com/discos/basie/ - -Installation instructions can be reduced to: - -``` -$ pip install -r requirements.txt -$ pip install . -``` - - - -Note that you may need to have root privileges for installing python packages. -If you wanna know more or you experience some issue, please go on reading. - -### EASY_INSTALL AND PIP - -We suggest to install dependencies via distutils. - -#### DISTUTILS ON WINDOWS - -From a command prompt try to execute the command - -``` -C:\your path\> easy_install -``` - -This will tell you if easy_install is installed on your Windows PC -If not just donwload and install python-setuptools package from -https://pypi.python.org/pypi/setuptools , go to the bottom of the page -and grab the .exe related to your python version. -If you're unsure which python version you are running from a command -prompt execute +#### Venv +To create a virtual environment using `venv`, you can follow these steps: -``` -C:\your path\> python --version -``` +1. Open your terminal or command prompt. -#### DISTUTILS ON LINUX +2. Navigate to the directory where you want to create your virtual environment. This could be the root directory of your project or any other location of your choice. -On linux you should find setuptools prepackaged on most modern distros. +3. Run the following command to create a new virtual environment: + ```$ python3 -m venv myenv``` -On debian-based distros: + Here, `myenv` is the name you choose for your virtual environment, and `python3` is the executable of the chosen (we recommend recent) Python version. You can replace it with any name you prefer. -```bash -you@yourpc$ sudo apt-get install python-setuptools -``` +4. Once the command completes, a new directory named myenv (or the name you chose) will be created in your current directory. This directory will contain all the necessary files and folders for your virtual environment. -On RH based distros: - -``` -root@yourpc$ yum install python-setuptools -``` +5. Activate the virtual environment by running the appropriate command based on your operating system, typically -Once easy_install is installed, instructions are the same for every -OS, so just follow the steps from command prompt or user shell. +```$ source /path/to/myenv/bin/activate``` -If possible we will use 'pip', a more friendly python package manager. -Install it with: +#### Conda +If you installed `anaconda` or `miniconda`, the process will be as simple as clicking a few buttons in the Anaconda GUI, or, from a shell, ``` -$ easy_install pip +$ conda create -n my_fancy_environment python=3.11 +$ conda activate my_fancy_environment ``` -### INSTALL PACKAGE DEPENDENCIES - +### Installing basie -You can install every dependecy via (note that you may need to be root): +Before installing the package make sure you download and extract the package +archive at +http://github.com/discos/basie/ -``` -$ make dep -``` -Or simply: +Installation instructions can be reduced to: ``` -$ pip install -r requirements.txt +$ pip install . ``` -### INSTALL +Note that, in some systems, you may need to have root privileges for installing python packages. +If you want to know more or you experience some issue, please go on reading. -From the package directory just run +You can remove basie via: ``` -$ pip install . +$ pip uninstall basie ``` -or +## KNOWN ISSUES -``` -$ make install -``` - -to install the package in the current python environment. -Now you can remove the downloaded package or clean build products via: +1. `NRAO CASA` is known to install its own version of Python and `pip`. We recommend installing CASA in its own `venv` or `conda` virtual environment to avoid conflicts. +In principle, it should be possible to install `basie` with `CASA`'s `pip`. -``` -$ make clean -``` +If you find an issue, please report it through [our Github Issue tracker](https://github.com/discos/basie/issues) ## USAGE diff --git a/doc/index.rst b/doc/index.rst index 3af6de6..188628f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,6 +10,7 @@ Contents: .. toctree:: :maxdepth: 2 + modules Indices and tables diff --git a/setup.cfg b/setup.cfg index efcf751..41adf42 100644 --- a/setup.cfg +++ b/setup.cfg @@ -65,6 +65,7 @@ docs = [options.entry_points] console_scripts = runbasie = basie:cmd_line + basie = basie:cmd_line # [options.packages.find] # where=basie