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:
“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
file:///path/to//abjad/docs/build/html/index.html to naviagate the build.