3.0.0rc1 (#1003)

* Preparing 3.0.0rc1 release

* Tidying-up documentation

* Purging ancient documentation

* More cleanup

* More cleanup

* Consolidate tests

* Add packaging instructions

* Don't clean-out docs on make release

* Fix tests

* Update pytest paths

* Bump uqbar requirement

* Cleanup

* Add subpackage summaries.

* Update README and setup.py

Makefile

@@ -19,5 +19,5 @@ release:
 	make clean
 	make docs
 	make build
-	make -C abjad/docs upload
+	make -C docs upload
 	twine upload dist/*.tar.gz

PACKAGING.md

@@ -0,0 +1,39 @@
+Abjad Packaging Checklist
+=========================
+
+Pre-packaging
+-------------
+
+- Open a branch for the new release: `release/x.y.z`
+- Remove references in the documentation to old events or no-longer-supported
+  versions of Python.
+- Verify that Abjad can be installed and run on an OSX machine, a Linux
+  machine, and a Windows machine. A virtual machine is acceptable for running
+  windows.
+- Verification includes: 
+  - Installation of Abjad and all dependencies, extension packages, and
+    third-party tools such as LilyPond and Graphviz.
+  - Running the test suite, including mypy.
+  - Building the documentation.
+  - Sanity checking `show()` and `play()`.
+  - Sanity check that the documentation looks acceptable.
+  - Running a Jupyter notebook with the IPython extension.
+- Fix any errors encountered during verification, push to the branch and
+  re-verify on all platforms.
+
+Packaging
+---------
+
+- Merge your release branch into master.
+- Create a release entry and tag on GitHub.
+- Have your PyPI credentials on hand.
+- Run `make release`. This will build the package, including the docs, push the
+  built package to PyPI and push the docs to our docs server.
+- Sanity check that the published release works as expected by installing it
+  into a new virtual environment.
+
+Post-release
+------------
+
+- Bump the version number in `abjad/_version.py` and push to master.
+- Announce on appropriate mailing lists.

README.rst

@@ -1,6 +1,6 @@
-##########
-Abjad 2.21
-##########
+#####
+Abjad
+#####
 
 Abjad helps composers build up complex pieces of music notation in an iterative
 and incremental way. Use Abjad to create symbolic representations of all the
@@ -53,16 +53,13 @@ Package Index, via `pip`_:
 **Caution**:
 
     We strongly encourage you to *not* install Abjad globally via ``sudo pip
-    install``, but to use a virtual environment instead. If you're already
-    working in a virtual environment, simply omit the ``sudo``.
+    install``, but to use a :ref:`virtual environment <virtual-environments>`
+    instead. If you're already working in a virtual environment, simply omit
+    the ``sudo``.
 
 **Note**:
 
-    Abjad supports Python 2.7 and above. Python 2.7.9 and above provide `pip`_
-    out-of-the-box. For earlier versions of Python 2.7, you may need to install
-    `pip`_ yourself. While you can use the old ``easy_install`` tool (``sudo
-    easy_install pip``), we strongly recommend the `pip`_-installation
-    instructions found here: https://pip.pypa.io/en/stable/installing/.
+    Abjad supports Python 3.6 and above.
 
 To install the cutting-edge version Abjad from its `GitHub`_ repository, via
 `git <https://git-scm.com/>`_ and `pip`_:
@@ -71,19 +68,19 @@ To install the cutting-edge version Abjad from its `GitHub`_ repository, via
 
     ~$ git clone https://github.com/Abjad/abjad.git 
     ~$ cd abjad
-    abjad$ sudo pip install .
+    abjad$ pip install .
 
 Once you have Abjad installed, fire up Python and import it:
 
 ..  code-block:: bash
 
     ~$ python
-    Python 3.6.2 (v3.6.2:5fd33b5926, Jul 16 2017, 20:11:06) 
+    Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 03:03:55) 
     [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import abjad
     >>> abjad.__version__
-    '2.21'
+    '3.0.0rc1'
 
 Congratulations!
 
@@ -105,7 +102,8 @@ command-line by running the following command:
 ..  code-block:: bash
 
     ~$ lilypond --version
-    GNU LilyPond 2.19.80
+
+    GNU LilyPond 2.19.82
 
     Copyright (c) 1996--2015 by
       Han-Wen Nienhuys <hanwen@xs4all.nl>
@@ -164,7 +162,22 @@ command-line by running the following command:
     dot - graphviz version 2.38.0 (20140413.2041)
 
 All of the graph images in Abjad's API documentation were created via
-`graphviz`_. See `topleveltools.graph()` for more details.
+`graphviz`_. See :py:func:`~abjad.top.graph` for more
+details.
+
+Install extension packages
+--------------------------
+
+Abjad's extension packages can be installed via the following commands:
+
+..  code-block:: bash
+
+    ~$ pip install abjad[book]      # documentation tools
+    ~$ pip install abjad[cli]       # score package command-line tools 
+    ~$ pip install abjad[ipython]   # ipython integration 
+    ~$ pip install abjad[nauert]    # quantization tools
+    ~$ pip install abjad[rmakers]   # rhythm-maker tools
+    ~$ pip install abjad[tonality]  # tonal analysis tools
 
 Development installation
 ------------------------
@@ -177,7 +190,7 @@ documentation locally, clone Abjad from the Github repository and install it in
 
     ~$ git clone https://github.com/Abjad/abjad.git
     ~$ cd abjad
-    abjad$ sudo pip install -e .[development]  # NOTE: no spaces in the string after "install"
+    abjad$ sudo pip install -e .[book,test]  # NOTE: no spaces in the string after "install"
 
 Installing Abjad in development mode will install the following `Python`_
 package dependencies (along with their own dependencies):
@@ -264,7 +277,7 @@ its **development** and **ipython** extra dependencies:
 
 ..  code-block:: bash
 
-    ~$ sudo pip install abjad[development,ipython]  # NOTE: no spaces in the string after "install"
+    ~$ sudo pip install abjad[ipython]  # NOTE: no spaces in the string after "install"
 
 Capturing MIDI files into an `IPython notebook`_ requires the `timidity`_
 package.
@@ -285,7 +298,7 @@ Once all dependencies have been installed, create a new `IPython notebook`_ and
 run the following "magic" command in a cell to load Abjad's `IPython`_
 extension::
 
-    %load_ext abjad.ext.ipython
+    %load_ext abjadext.ipython
 
 Once loaded, notation and MIDI files can be embedded in your notebook whenever
 you use `show(...)` and `play(...)` on valid Abjad objects.
@@ -456,7 +469,6 @@ you might want to set your ``pdf_viewer`` to ``evince`` and your
 ..  _MacTeX: https://tug.org/mactex/
 ..  _PyPDF2: http://pythonhosted.org/PyPDF2/
 ..  _PyPI: https://pypi.python.org/pypi/Abjad
-..  _PyPy: http://pypy.org/
 ..  _Python: https://www.python.org/
 ..  _Sphinx: http://sphinx-doc.org/
 ..  _TeXLive: https://www.tug.org/texlive/

abjad/__init__.py

@@ -66,15 +66,3 @@
 
 # singletons
 tags = system.Tags()
-
-# HOUSECLEANING HELPER: uncomment below and run tests;
-#                       checks for hasattr() calls against properties:
-#def hasattr_warn(argument, name, original_hasattr=hasattr):
-#    if original_hasattr(argument.__class__, name):
-#        value = getattr(argument.__class__, name)
-#        if isinstance(value, property):
-#            message = 'WARNING: {}.{} is a property!'
-#            message = message.format(argument.__class__.__name__, name)
-#            raise Exception(message)
-#    return original_hasattr(argument, name)
-#__builtins__['hasattr'] = hasattr_warn

abjad/_version.py

@@ -1,2 +1,5 @@
-__version_info__ = (3, 0)
-__version__ = '.'.join(str(x) for x in __version_info__)
+__version_info__ = (3, 0, 0, 'rc1')
+__version__ = (
+    '.'.join(str(x) for x in __version_info__[:3]) +
+    ''.join(__version_info__[3:] or [])
+)

abjad/cli.py

@@ -1,3 +1,7 @@
+"""
+Command-line tools.
+"""
+
 import fnmatch
 import importlib
 import inspect

abjad/core/__init__.py

@@ -1,3 +1,8 @@
+"""
+Abjad's core component classes: notes, rests, chords, tuplets, measures,
+containers and contexts.
+"""
+
 from .Component import Component
 from .Container import Container
 from .GraceContainer import GraceContainer
@@ -34,5 +39,3 @@
 from .Tuplet import Tuplet
 from .VerticalMoment import VerticalMoment
 from .Voice import Voice
-
-_documentation_section = 'core'

abjad/demos/__init__.py

@@ -1,3 +1,7 @@
+"""
+Literature examples implemented in Abjad.
+"""
+
 from abjad.demos import bartok
 from abjad.demos import ferneyhough
 from abjad.demos import ligeti

abjad/enums.py

@@ -1,3 +1,7 @@
+"""
+Enumerations.
+"""
+
 import uqbar.enums
 
 
@@ -41,8 +45,6 @@ class VerticalAlignment(uqbar.enums.StrictEnumeration):
     Down = -1
     Center = 0
     Up = 1
-    Default = 0  # aliases Center
-    Neutral = 0  # aliases Center
 
     def __format__(self, format_spec):
         """

abjad/exceptions.py

@@ -1,3 +1,7 @@
+"""
+Custom exceptions.
+"""
+
 class AssignabilityError(Exception):
     r'''Duration can not be assigned to note, rest or chord.
     '''

abjad/indicators/__init__.py

@@ -1,3 +1,7 @@
+"""
+Tools for modeling "indicators".
+"""
+
 from .Arpeggio import Arpeggio
 from .Articulation import Articulation
 from .BarLine import BarLine
@@ -33,5 +37,3 @@
 from .TimeSignature import TimeSignature
 from .Tremolo import Tremolo
 from .WoodwindFingering import WoodwindFingering
-
-_documentation_section = 'core'

abjad/instruments.py

@@ -1,3 +1,7 @@
+"""
+Instrument classes.
+"""
+
 import copy
 import typing
 from abjad.system.AbjadValueObject import AbjadValueObject

abjad/lilypondfile/__init__.py

@@ -1,3 +1,7 @@
+"""
+Tools for modeling high-level constructs in LilyPond's file format.
+"""
+
 from .Block import Block
 from .ContextBlock import ContextBlock
 from .DateTimeToken import DateTimeToken
@@ -6,5 +10,3 @@
 from .LilyPondLanguageToken import LilyPondLanguageToken
 from .LilyPondVersionToken import LilyPondVersionToken
 from .PackageGitCommitToken import PackageGitCommitToken
-
-_documentation_section = 'core'

abjad/lilypondnames/__init__.py

@@ -1,3 +1,7 @@
+"""
+Tools for modeling LilyPond's "grobs", "context", "engravers", etc.
+"""
+
 from .LilyPondContext import LilyPondContext
 from .LilyPondContextSetting import LilyPondContextSetting
 from .LilyPondEngraver import LilyPondEngraver
@@ -8,5 +12,3 @@
 from .LilyPondGrobOverride import LilyPondGrobOverride
 from .LilyPondSettingNameManager import LilyPondSettingNameManager
 from .LilyPondTweakManager import LilyPondTweakManager
-
-_documentation_section = 'internals'

abjad/ly/__init__.py

@@ -1,3 +1,7 @@
+"""
+Abjad's scrape of LilyPond's execution environment.
+"""
+
 from abjad.ly.contexts import contexts
 from abjad.ly.current_module import current_module
 from abjad.ly.drums import drums

abjad/markups.py

@@ -1,3 +1,7 @@
+"""
+Tools for modeling LilyPond's markup and postscript.
+"""
+
 import collections
 import numbers
 import typing

abjad/mathtools/__init__.py

@@ -45,5 +45,3 @@
 from .sign import sign
 from .weight import weight
 from .yield_all_compositions_of_integer import yield_all_compositions_of_integer
-
-_documentation_section = 'core'

abjad/meter.py

@@ -1,3 +1,7 @@
+"""
+Tools for modeling musical meter.
+"""
+
 import bisect
 import collections
 import uqbar.graphs

abjad/parser/__init__.py

@@ -1,3 +1,7 @@
+"""
+Abjad's LilyPond parser and supporting classes.
+"""
+
 from .Music import Music
 from .ContextSpeccedMusic import ContextSpeccedMusic
 from .GuileProxy import GuileProxy
@@ -16,5 +20,3 @@
 from .SimultaneousMusic import SimultaneousMusic
 from .SyntaxNode import SyntaxNode
 from .parse_reduced_ly_syntax import parse_reduced_ly_syntax
-
-_documentation_section = 'internals'

abjad/pitch/__init__.py

@@ -1,3 +1,6 @@
+"""
+Tools for modeling and manipulating 24ET pitches.
+"""
 from .constants import *
 from .Accidental import Accidental
 from .ColorMap import ColorMap
@@ -42,5 +45,3 @@
 from .StaffPosition import StaffPosition
 from .Transposition import Transposition
 from .TwelveToneRow import TwelveToneRow
-
-_documentation_section = 'core'

abjad/rhythmtrees.py

@@ -1,3 +1,7 @@
+"""
+Tools for modeling "rhythm-trees".
+"""
+
 import abc
 import typing
 import uqbar.containers