Developer installation¶
What’s the difference between “packaged” and “cloned” installation? How can a local build of Abjad’s docs be made for viewing offline?
“Packaged” versus “cloned” installs of Abjad¶
The majority of users install Abjad from the Python Package Index:
https://abjad.github.io/first_steps/macos.html
https://abjad.github.io/first_steps/linux.html
“Packaged” installation of Abjad is recommended for most users. Python installs the current release of Abjad into the site-packages directory of the Python virtual environment active at the time of installation. Installing Abjad from package means that a user intends to compose with Abjad, but not develop Abjad.
Abjad can be installed another way, too. Clone Abjad from GitHub and then use pip to install the clone in “editable” mode:
~$ git clone https://github.com/Abjad/abjad.git
~$ cd abjad
abjad$ python -m pip install --editable .[dev]
“Cloned” installation of Abjad is necessary for users who want to develop Abjad. Cloned installation is also required for users who want to build Abjad’s docs locally.
Building Abjad’s docs locally¶
The most recent version of Abjad’s docs is hosted here:
This means that most users do not need to build Abjad’s docs locally. Users who do want to build Abjad’s docs locally should clone and install Abjad as shown above. Then make sure TeXLive and Graphviz are installed.
To install Graphviz on macOS via Homebrew:
~$ brew install graphviz
To install Graphviz on Debian and Ubuntu:
~$ sudo apt-get install graphviz
To check that Graphviz is callable from the commandline after install:
~$ dot -V
dot - graphviz version 2.40.1 (20161225.0304)
Make a local version of the docs like this:
~$ cd path/to/abjad/docs
~$ make html
The build process takes a long time the first time it runs. Finished output is available here:
~$ ls path/to/abjad/docs/build/html
_images _static gallery-2010.html objects.inv sidebar.html
_modules api gallery-2015.html overview welcome
_mothballed appendices gallery-2020.html py-modindex.html
_pending examples genindex.html search.html
_sources first_steps index.html searchindex.js
Browse file:///path/to//abjad/docs/build/html/index.html
to naviagate the build.