Merge pull request #1431 from cuthbertLab/modern-install-system

Modern install system

.gitignore

@@ -21,6 +21,7 @@ __pycache__/
 
 # OSX
 .DS_Store
+**/.DS_Store
 
 # C extensions
 *.so
@@ -40,6 +41,7 @@ develop-eggs
 lib
 lib64
 __pycache__
+**/__pycache__
 venv
 
 # Installer logs

CONTRIBUTING.md

@@ -19,6 +19,17 @@ own projects that import and extend `music21`.
 [Code of Conduct](README.md)
 
 
+## Preparing to Contribute ##
+
+Be sure to install all of the requirements in `requirements_dev.txt` via:
+
+```
+pip3 install -r requirements_dev.txt
+```
+
+There are several tools needed for fully testing music21 that aren't included
+in the standard `requirements.txt`.
+
 ## Issue Tickets ##
 
 Please use the provided templates for bug reports or feature proposals. For issues

README.md

@@ -1,8 +1,9 @@
 # music21 #
 
-music21 -- A Toolkit for Computational Musicology
+`music21` -- A Toolkit for Computer-Aided Musical Analysis and 
+Computational Musicology
 
-Copyright © 2006-2022, Michael Scott Asato Cuthbert
+Copyright © 2006-2022, [Michael Scott Asato Cuthbert](http://www.trecento.com)
 
 For more information, visit:
 https://web.mit.edu/music21
@@ -13,13 +14,13 @@ https://tinyurl.com/m21colab
 And to install, see:
 https://web.mit.edu/music21/doc/usersGuide/usersGuide_01_installing.html
 
-Music21 runs on Python 3.8+.  Use version 4 on Python 2 or Py3.4, version 5
+`Music21` runs on Python 3.8+.  Use version 4 on Python 2 or Py3.4, version 5
 on Py3.5, version 6 on Py3.6, version 7 on Py3.7.
 
 Released under the BSD (3-clause) license. See LICENSE.
 Externally provided software (including the MIT licensed Lilypond/MusicXML test Suite) and
 music encoding in the corpus may have different licenses and/or copyrights. 
-A no-corpus version of music21 is available also on GitHub.
+A no-corpus version of `music21` is available also on GitHub.
 
 [![Build Status](https://github.com/cuthbertLab/music21/workflows/maincheck/badge.svg)](https://github.com/cuthbertLab/music21)
 [![Lint Status](https://github.com/cuthbertLab/music21/workflows/PyLint/badge.svg)](https://github.com/cuthbertLab/music21)
@@ -41,7 +42,7 @@ See: https://groups.google.com/forum/#!forum/music21list
 
 ## Community Code of Conduct ##
 
-Music21 encourages contributions, discussions, and usage from all people interested in
+`Music21` encourages contributions, discussions, and usage from all people interested in
 music and computers. This encouragement extends to all people regardless of (among other aspects)
 gender, race, sexual orientation, disability, religion, appearance, veteran status,
 gender identity, socioeconomic status, or nationality.
@@ -56,7 +57,15 @@ sometimes make mistakes and will, in general, accept sincere regrets for such ca
 Blatant or repeated violations of the code will result in the removal of the
 contributor’s participation in the community.
 
-The maintainers of music21 and associated sites will commit themselves to enforcing
+The maintainers of `music21` and associated sites will commit themselves to enforcing
 this code of conduct. Users who notice violations, including instances of abuse,
 harassment, or otherwise unacceptable behavior are requested to contact [email protected].
 Maintainers will respect confidentiality with regard to reports.
+
+## Acknowledgements ##
+
+The development of `music21` has been supported by
+the generosity of the Seaver Institute and the
+National Endowment for the Humanities.  MIT's Music and Theater Arts Section
+and the School of Humanities, Arts, and Social Sciences encouraged Cuthbert
+in its development.

documentation/source/installing/installLinux.rst

@@ -4,20 +4,27 @@
 Installing `music21` on GNU/Linux
 ============================================
 
-GNU/Linux, FreeBSD, etc. are supported by `music21`. However, by choosing to use 
-Unix-like systems you should be an advanced user -- the music21list should not
-be used for general installation/configuration problems that are specific to
+GNU/Linux, FreeBSD, etc. generally work on `music21`.  Many people, including
+all of the major developers of `music21` run it on various deployed GNU/Linux,
+Unix, AWS-Unix, etc. systems throughout the world.  However, no system except
+recent Mac and Windows OSes are officially supported.
+
+By choosing to use Unix-like systems you should be an advanced user on your
+OS, able to deal with the issues of libraries, linkage, external files, etc.
+specific to (and different on) each Unix-like system.  The music21list should not
+be used for installation/configuration problems on
 your operating system. Because of the number of different Unix variants, the list
-maintainers can only help with `music21`-specific problems post installation or
-Mac/PC problems.
+maintainers will only entertain `music21`-specific problems on Unix **post**
+installation and configuration.
 
-To reiterate: **GNU/Linux is not a system for which support questions will be answered**
+To reiterate: **GNU/Linux is not a system for which support
+questions will be answered**
 
 
 Check Your Version of Python
 ----------------------------------------------
 
-`Music21` requires Python 3.7+.
+`Music21` requires Python 3.8+.
 
 To determine the Python version you have installed, open a shell 
 or terminal and enter the following command-line argument (where "$" is the prompt):
@@ -26,11 +33,11 @@ or terminal and enter the following command-line argument (where "$" is the prom
 
 it should display something like:
 
-    Python 3.9.2
+    Python 3.10.7
 
-if so, you're okay.  If not, go to https://www.python.org/downloads/
-and download a newer version.  Multiple versions of Python can exist 
-on a single computer without any problems. 
+if so, you're okay.  If not, upgrade your version of Python.  This is
+often a problem on some AWS configuations, Google Colab, etc.
+which do not ship by default with recent versions of Python.
 
 
 Download `music21` 
@@ -41,10 +48,24 @@ Download the newest version with:
     pip3 install --upgrade music21
 
 
+Configure `music21`
+----------------------------------------------
+Configure music21 with:
+
+    python3 -m music21.configure
+
+It is important to put the path to your MusicXML reader during these
+prompts.  Music21 cannot find where your XML reader (probably MuseScore)
+is installed on most Unix/Linux systems.  If you do not know about
+filepaths and how to find them, you should probably not be using
+GNU/Linux, FreeBSD, etc. with `music21`.
+
+
 After Installation
 -------------------------------
 
-After a successful installation, you may proceed to :ref:`Notes <usersGuide_02_notes>` to 
+After a successful installation, you may proceed to
+:ref:`Notes <usersGuide_02_notes>` to
 begin using `music21`.
 
 
@@ -53,6 +74,7 @@ Installation Help
 
 If you have followed all the instructions and still encounter problems, 
 start over from scratch and try it again very carefully.  
-If you still have problems contact an expert in your operating system.
-The `music21` staff cannot help with Unix installation problems except
-as paid support.
+If you still have problems **contact an expert in your operating system**.
+
+The `music21` maintainers cannot help with Unix installation problems except
+as paid support.  See Consulting in the FAQ for details on paid support.

documentation/source/installing/installMac.rst

@@ -13,14 +13,15 @@ Trust us that it should work.
 Downloading Python 3 from python.org
 ---------------------------------------
 
-Though Macs come with Python, it's a very old version.  We recommend
-updating that by going to https://www.python.org/downloads and getting
-Python 3.9 or later.
+Though most Macs come with Python, it's usually a very old version.
+We recommend updating that by going to https://www.python.org/downloads
+and getting the latest version.
 
 (The `music21` team strongly recommends using the version of
 Python 3 from the python.org website and not the Conda version
-(or Enthought Canopy) because it is fully compatible with
-`matplotlib`.  If you have no plans on plotting functions,
+(or Enthought Canopy) because music21 is fully compatible with
+`matplotlib` on the python.org site.
+If you have no plans on plotting functions,
 feel free to use any flavor of Python 3.)
 
 
@@ -65,7 +66,7 @@ it should display in Terminal something like the following:
 .. image:: images/macScreenPythonVersion.*
     :width: 650
 
-If it says 3.7 or higher (or possibly a number like 3.9.2), you're okay.
+If it says 3.8 or higher (or possibly a number like 3.10.7), you're okay.
 If it says 2.7 or 3.4 or something,
 go to https://www.python.org/downloads/
 and download a newer version.  Multiple versions of Python can exist
@@ -88,56 +89,24 @@ Exit python by typing `quit()`.
 Starting the Configuration Assistant
 -----------------------------------------------------
 
-If you downloaded the `music21` project from Github, the project folder will
-contain a script that runs a configuration assistant. Double click on the
-installer.command file to start. This should open a Terminal window and run
-the Configuration Assistant. As this is a program downloaded from the Internet,
-the System will likely warn you about running it. Go ahead and click "Open".
+If you only installed the `music21` package with `pip` (for
+instance, by running `sudo pip3 install music21`), you should run
+the assistant from a command prompt::
 
-More likely, if you only installed the `music21` package with `pip` (for
-instance, by running `sudo pip3 install music21`), you may run the Configuration
-Assistant from a Python shell after importing `music21`, like this::
+    python3 -m music21.configure
+
+You can also run the Configuration Assistant from a Python shell
+ like this::
 
     import music21
     music21.configure.run()
 
-Otherwise, you may launch the assistant from a command prompt::
-
-    python3 -m music21.configure
-
 After waiting a few moments to load modules, the Configuration Assistant begins.
 
 .. image:: images/macScreenConfigAssistantStart.*
     :width: 650
 
-The first option is to install `music21` in its standard location
-(see below, The Installation Destination). Enter "y" or "yes", or
-press return to accept the default of "yes".  If you installed via pip, you
-won't be asked this question.
-
-Before installation begins you may be asked for your Mac password. (The cursor
-won't move or display any letters when you type in the password.  Just rest assured
-that the characters are being transmitted).
-As Python packages are stored in a System directory, you need to give permission
-to write files to that location.
-
-(If you don't get a prompt but instead start getting
-a lot of errors, you probably do not have an administrator account on your Mac.
-To make yourself one, quit the installation program (just close the window), open
-System Preferences from the Apple menu in the upper left corner of your screen, click on
-Users and Groups (4th Row).  Click on the lock on the lower-left corner -- you'll need
-your Mac password.  Then click "Allow user to administer this computer".  Then
-close System Preferences and click the music21 `installer.command` button again and
-go back one step.)
-
-During installation, a large amount of text will display showing files being copied.
-Sorry about the mess.  Just ignore it!  It means it's working.
-
-.. image:: images/macScreenConfigAssistantStart.*
-    :width: 650
-
-After installation the Configuration Assistant will try to
-configure your setup. If you have never used `music21` before,
+If you have never used `music21` before,
 following these prompts is recommended.
 
 Selecting a MusicXML reader is the first step.
@@ -149,7 +118,7 @@ The Configuration Assistant will attempt to find a MusicXML
 reader on your system. If it can't find any, you will be asked
 to open a URL to download MuseScore, a simple and free
 MusicXML reader and easy writer. Installing MuseScore is
-recommended for users who do not have Finale, Sibelius, MuseScore,
+recommended for users who do not have Finale, Sibelius, Dorico, MuseScore,
 or another MusicXML reader.
 
 If one or more MusicXML readers are found, skip ahead to the next instructions.

documentation/source/installing/installWindows.rst

@@ -13,7 +13,7 @@ is written in and in which you will write your own programs that
 use `music21`.
 
 Windows users should download and install Python version
-3.8 or higher.
+3.10 or higher.
 
 To get Python for Windows, go to https://www.python.org/downloads/
 and click on the "Windows installer" link.  It is probably the
@@ -37,7 +37,7 @@ typing in "IDLE" or (on Windows Vista and newer) typing
 in "IDLE" in the Search Programs list.
 
 The first lines of text displayed will include a version number.
-Make sure it begins with 3.7 or higher.
+Make sure it begins with 3.10 or higher.
 
 If your version is too old, download a newer version as above.
 
@@ -66,15 +66,15 @@ Python on your system.  Try uninstalling all of them along with `music21`
 and then restarting from scratch).
 
 You should then configure `music21` to find your helper programs
-such as MuseScore or Finale.  In IDLE
-type::
+such as MuseScore or Finale.  In the command prompt, type::
+
+    python3 -m music21.configure
+
+Or, in IDLE type::
 
     import music21
     music21.configure.run()
 
-or in the command prompt, type::
-
-    python3 -m music21.configure
 
 After Installation
 -------------------------------