Text based document generation using Python 3.x

»Home  »User Guide  »Download  »Install  »Quickstart  »PyPI  »Windows  »Release Notes  »Blog  »Donate  »Contact  »Imprint / Impressum / Datenschutz

1. Overview

To install AsciiDoc3 via pip (pip3), you’ll find the information you need on this page.

Warning Unfortunately at the moment AsciiDoc3 and PyPI on Windows seem to have some limitations. We are working on this issue.

1.1. PyPI

AsciiDoc3-3.0.2 is available at PyPI:
The current version is asciidoc3 3.0.2b1

Note AsciiDoc3 PyPI is beta!
Qestion: What does this mean?
Answer: You can use AsciiDoc3 in a save and convenient way, but please consider the following annotations.
Warning Do not forget the steps described in asciidoc3_postinstall, see here!

1.2. Pip3

Before you start, be sure to have pip3 installed:

$ pip3

  pip <command> [options]

  install                     Install packages.
  download                    Download packages.

It is impossible to cover all pip issues on every os out there …,

1.3. Scenarios

We have the following three scenarios, see the information given in the sections below:

  • AsciiDoc3 local in the user’s virtual env: pip install asciidoc3, recommended,

  • AsciiDoc3 local in the user’s home directory ~/.local/…, no virtual env: pip install --user asciidoc3,

  • AsciiDoc3 system wide: (su/sudo) pip install asciidoc3 — not recommended!

2. AsciiDoc3 Pip Install

This is the recommended way: install AsciiDoc3 local in the user’s virtual env. Look at this example:

$ apt-get install python3-venv

$ python3 -m venv /home/<username>/ad3test

$ cd /home/<username>/ad3test

$ source /home/<username>/ad3test/bin/activate

(ad3test): ~ad3test$ pip install wheel      # to avoid error: "invalid command 'bdist_wheel'" in the next step

(ad3test): ~ad3test$ pip install asciidoc3  # do NOT use option --user
  Successfully installed asciidoc3

(ad3test): ~ad3test$

The files are now installed in directory ~ad3test/bin or ~ad3test/lib/python3.5/site-packages/asciidoc3.

Unfortunately we are not ready now! AsciiDoc3 comes with a bundle of configuration files. They are now hidden in your venv-directory (e.g. ~ad3test/lib/python3.5/site-packages/asciidoc3/asciidoc3.conf) and if you run asciidoc3 from the command line the output says no help topics found. AsciiDoc3 does not know where the files are …
And a second issue pops up: pip installs no symlinks which are needed for convenient work (e. g., the images are not found when running a filter).
But there is a solution: run asciidoc3_postinstall! See below.

2.2. AsciiDoc3 in directory ~/.local

You may of course install AsciiDoc3 local without using venv. Don’t forget to add option --user.

$ pip install --user asciidoc3

We have the same issue as described in the previous section (conf-files and images are hidden). asciidoc3_postinstall helps, see below.

This is not recommended, but - at your choice, of course - possible. You are on your own to manage the symlinks in a proper way - see here.
If you like to install system wide you better choose the tarball here.

(root su/sudo): pip install asciidoc3

The files are installed in the directories /usr/local/bin/asciidoc3 and /usr/local/lib/python3.5/dist-packages/asciidoc3.

2.4. asciidoc3_postinstall

To run asciidoc3_postinstall immediately after install via pip is highly recommendable.
Python’s setuptools/pip do not support symlinks. The script sets the appropriate relative symlinks inside the AsciiDoc3-directories to make the images available from the diverse subdirectories. You may skip this, but in this case you have to set manually the options in the command line or in the conf-files (a very annoying thing btw!).
In a second step asciidoc3_postinstall creates the new directories ~/.asciidoc3 and ~/asciidoc3, which are both symlinks to directory asciidoc3 created via pip.
To have these two symlinks, which spend no aditional disk space, makes the use of AsciiDoc3 much more convenient: AsciiDoc3 searches for the most conf-files in ~/.asciidoc3 and ~/asciidoc3 without the dot makes the files visible to your file manager.

(ad3test): ~ad3test$ asciidoc3_postinstall
(ad3test): ~ad3test$
Note Of course you can vary, add, or delete all directory / symlink names to fit your needs.

3. Miscellaneous

3.1. Work with AsciiDoc3

As soon as you ran successfully pip and asciidoc3_postinstall you can start working with AsciiDoc3:

$ source /home/<username>/ad3test/bin/activate

(ad3test): cd ~/asciidoc3
(ad3test): cd doc
(ad3test): asciidoc3 -a toc -a icons -n test.txt
(ad3test): asciidoc3 -a toc -a icons -n userguide.txt
(ad3test): a2x3 -f pdf test.txt
(ad3test): a2x3 -f pdf userguide.txt

The output is found in the same dir ~/asciidoc3/doc.
You may follow the steps described here.

3.2. Uninstall

You may uninstall AsciiDoc3:

$ pip uninstall asciidoc3
Note You have to delete all symlinks added by asciidoc3_postinstall manually; pip removes only the files it has itself installed.

3.3. Not on PATH

Some users with debian/ubuntu flavors (and other?) will encounter the following message

$ pip3 install --user asciidoc3

  The scripts a2x3 and asciidoc3 are installed in '/home/<usrename>/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.

$ PATH=$PATH:/home/<username>/.local/bin
$ export PATH
Note Changing PATH in the shown way is only valid in this particular session. To make this behaviour permanent you have to edit ~.bashrc (or other conf-files). The appropriate way depends on your os and shell.

3.4. Anaconda and AsciiDoc3