Merge pull request #197 from MontrealCorpusTools/v1.3

Documentation update to version 1.3

.travis.yml

@@ -1,6 +1,6 @@
 language: python
 python:
- - 3.8
+ - 3.12
 branches:
  only:
  - main
@@ -14,7 +14,6 @@ sudo: required
 addons:
  apt:
  packages:
- - openjdk-11-jdk
  - sox
  - libsndfile1
 
@@ -34,24 +33,23 @@ install:
  - pip install -r requirements.txt
  - which python
  - conda list
- - python bin/pgdb install -q
- - python bin/pgdb start
+ - python polyglotdb/pgdb.py start
 
 before_script:
  - sleep 15
 
 # Run test
 script:
  - source activate test-environment
- - coverage run --source=polyglotdb setup.py test
+ - coverage run -m pytest
 
 after_script:
  - source activate test-environment
- - python bin/pgdb stop
+ - python polyglotdb/pgdb.py stop
 
 # Calculate coverage
 after_success:
- - coveralls
+ - coveralls 
 
 cache:
  pip: true

continuous-integration/travis/install.sh

@@ -11,11 +11,11 @@ if [ ! -d "$HOME/miniconda/miniconda/envs/test-environment" ]; then
  conda config --set always_yes yes --set changeps1 no
  conda update -q conda
  conda info -a
- conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION setuptools numpy pytest scipy
+ conda create -q -n test-environment -c conda-forge openjdk=21 pip
  conda activate test-environment
  which python
- pip install -q coveralls coverage neo4j-driver textgrid librosa tqdm influxdb conch_sounds
- python setup.py install
+ pip install -q coveralls coverage neo4j textgrid librosa tqdm influxdb conch_sounds pytest
+ pip install -q -e .
 else
  export PATH="$HOME/miniconda/miniconda/bin:$PATH"
  source "$HOME/miniconda/miniconda/etc/profile.d/conda.sh"
@@ -38,7 +38,7 @@ if [ ! -f "$HOME/tools/praat" ]; then
  grep -Eo 'praat[0-9]+_linux64barren\.tar\.gz' | head -1)
 
  # Download.
- curl "https://www.fon.hum.uva.nl/praat/praat6151_linux64barren.tar.gz" > praat-latest.tar.gz
+ curl "https://www.fon.hum.uva.nl/praat/praat6414_linux-intel64-barren.tar.gz" > praat-latest.tar.gz
  tar -zxvf praat-latest.tar.gz
  mv praat_barren $HOME/tools/praat
 else

docs/source/changelog.rst

@@ -3,6 +3,15 @@
 Changelog
 *********
 
+
+Version 1.3.0
+=============
+
+* Updated Neo4j Cypher queries to be compatible with Neo4j 5.x syntax.
+* Upgraded Neo4j compatibility to version 5.22 and Java compatibility to Java 21.
+* Updated the packaging process for smooth installation across platforms.
+* Made Conda a required installation dependency.
+
 Version 1.2.1
 =============
 
@@ -27,4 +36,4 @@ Version 1.0
 * Added ability to enrich tokens from CSV
 * Added parser for TextGrids generated from the Web-MAUS aligner
 * Optimized loading of corpora for lower-memory computers
-* Optimized queries involving acoustic tracks
+* Optimized queries involving acoustic tracks

docs/source/conf.py

@@ -15,7 +15,7 @@
 
 import sys
 import os
-
+from importlib.metadata import version as get_version
 import mock
 
 MOCK_MODULES = ['textgrid', 'textgrid.textgrid',
@@ -94,17 +94,12 @@
 
 # General information about the project.
 project = 'PolyglotDB'
-copyright = '2015-2019, Montreal Corpus Tools'
+copyright = '2015-2024, Montreal Corpus Tools'
 author = 'Montreal Corpus Tools'
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '{}.{}'.format(polyglotdb.__ver_major__, polyglotdb.__ver_minor__)
-# The full version, including alpha/beta/rc tags.
-release = polyglotdb.__version__
+release: str = get_version("polyglotdb")
+# for example take major/minor
+version: str = ".".join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/getting_started.rst

@@ -2,6 +2,8 @@
 
 .. _installation:
 
+.. _Conda Installation: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html
+
 ***************
 Getting started
 ***************
@@ -25,42 +27,48 @@ dependencies that must be installed prior to using a Polyglot database, dependin
 Installation
 ============
 
+It is recommended to create an insolated conda environment for using PolyglotDB, for ensuring the correct Java version as well as better package management with Python. 
+
+If you don't have conda installed on your device: 
+
+#. Install either Anaconda, Miniconda, or Miniforge (`Conda Installation`_)
+#. Make sure your conda is up to date :code:`conda update conda`
+
+.. note::
+ On Windows, you should use Anaconda Prompt or Miniforge Prompt in order to use conda.
+
 To install via pip:
 
-``pip install polyglotdb``
+#. Create the a conda environment via :code:`conda create -n polyglotdb -c conda-forge openjdk pip`
+#. Activate conda environment :code:`conda activate polyglotdb`
+#. Install PolyglotDB via :code:`pip install polyglotdb`, which will install the ``pgdb`` utility that can be run inside your conda environment 
+ and manages a local database.
 
 To install from source (primarily for development):
 
 #. Clone or download the Git repository (https://github.com/MontrealCorpusTools/PolyglotDB).
-#. Navigate to the directory via command line and install the dependencies via :code:`pip install -r requirements.txt`
-#. Install PolyglotDB via :code:`python setup.py install`, which will install the ``pgdb`` utility that can be run anywhere
+#. Navigate to the directory via command line and create the conda environment via :code:`conda env create -f environment.yml`
+#. Activate conda environment :code:`conda activate polyglotdb-dev`
+#. Install PolyglotDB via :code:`pip install -e .`, which will install the ``pgdb`` utility that can be run inside your conda environment
  and manages a local database.
 
-.. note::
-
- The use of ``sudo`` is not recommended for installation. Ideally your Python installation should be managed by either
- Anaconda or Homebrew (for Macs).
-
 .. _local_setup:
 
 Set up local database
 ---------------------
 
-Installing the PolyglotDB package also installs a utility script (``pgdb``) that is then callable from the command line
-anywhere on the system. The ``pgdb`` command allows for the administration of a single Polyglot database (install/start/stop/uninstall).
+Installing the PolyglotDB package also installs a utility script (``pgdb``) that is then callable from the command line inside your conda environment. 
+The ``pgdb`` command allows for the administration of a single Polyglot database (install/start/stop/uninstall).
 Using ``pgdb`` requires that several prerequisites be installed first, and the remainder of this section will detail how
 to install these on various platforms.
 Please be aware that using the ``pgdb`` utility to set up a database is not recommended for larger groups or those needing
 remote access.
 See the `ISCAN server`_ for a more fully featured solution.
 
-Mac
-```
-
-#. Ensure Java 11 is installed inside Anaconda distribution (``conda install -c anaconda openjdk``) if using Anaconda, or
- via Homebrew otherwise (``brew cask install java``)
-#. Check Java version is 11 via ``java --version``
-#. Once PolyglotDB is installed, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
+Mac & Linux
+```````````
+#. Make sure you are inside the dedicated conda environment just created. If not, activate it via :code:`conda activate polyglotdb`
+#. Inside your conda environment, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
  :code:`pgdb install` to save data in the default directory.
 
 .. warning::
@@ -75,66 +83,18 @@ To uninstall, run :code:`pgdb uninstall`
 Windows
 ```````
 
-#. Ensure Java 11 is installed (https://www.java.com/) and on the path (``java --version`` works in the command prompt)
-#. Check Java version is 11 via ``java --version``
-#. Start an Administrator command prompt (right click on cmd.exe and select "Run as administrator"), as Neo4j will be installed as a Windows service.
-#. Run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
+#. Make sure you are running as an Administrator (right-click on Anaconda Prompt/Miniforge Prompt and select "Run as administrator"), as Neo4j will be installed as a Windows service.
+#. If you had to reopen a command prompt in Step 1, reactivate your conda environment via: :code:`conda activate polyglotdb`.
+#. Inside your conda environment, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
  :code:`pgdb install` to save data in the default directory.
 
-To start the database, you likewise have to use an administrator command prompt before entering the commands :code:`pgdb start`
+To start/stop the database, you likewise have to use an administrator command prompt before entering the commands :code:`pgdb start`
 or :code:`pgdb stop`.
 
 To uninstall, run :code:`pgdb uninstall` (also requires an administrator command prompt).
 
-Linux
-`````
-
-Ensure Java 11 is installed. On Ubuntu:
-
-.. code-block:: bash
-
- sudo apt-get update
- sudo apt-get install openjdk-11-jdk-headless
-
-Once installed, double check that ``java --version`` returns Java 11. Then run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
-:code:`pgdb install` to save data in the default directory.
-
-Once you have installed PolyglotDB, to start it run :code:`pgdb start`.
-Likewise, you can close PolyglotDB by running :code:`pgdb stop`.
-
-To uninstall, navigate to the PolyglotDB directory and type :code:`pgdb uninstall`
-
-
-Conda Development Environment
-============
-
-You can also use conda to create an isolated polyglotdb development environment:
-
-#. Install either Anaconda, miniconda, or miniforge 
-#. Make sure your conda is up to date (conda update conda)
-#. Make sure that you have cloned the polyglotdb repository
-#. cd to the source directory
-
-We’ll now kick off a two-step process:
-
-#. Create a conda environment to isolate polyglotdb dependencies
-#. Build and install polyglotdb
-
-.. code-block:: bash
-
- conda env create -f environment.yml
- conda activate polyglotdb-dev
-
-From within the polyglotdb-dev environment, double check that ``java --version`` returns Java 11. Then:
-
-.. code-block:: bash
-
- python setup.py install
- pgdb install /path/to/where/you/want/data/to/be/stored
-
-You now have a new conda environment that is isolated from any existing environments or python installations. The pgdb executable will only be accessible from within the polyglotdb-dev environment.
 
-To view your environments:
+To view your conda environments:
 
 .. code-block:: bash
 

rtd_requirements.txt

@@ -2,3 +2,4 @@ sphinx
 numpydoc
 mock
 sphinx_rtd_theme
+polyglotdb