[hawkmoth] [PATCH 5/5] doc: add detailed installation instructions

  • From: Jani Nikula <jani@xxxxxxxxxx>
  • To: hawkmoth@xxxxxxxxxxxxx
  • Date: Wed, 30 Dec 2020 21:42:31 +0200

Document some of the pitfalls in the Clang dependency in particular.
---
 README.rst           | 13 +++----
 doc/extension.rst    |  7 +++-
 doc/index.rst        |  6 ++-
 doc/installation.rst | 89 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 103 insertions(+), 12 deletions(-)
 create mode 100644 doc/installation.rst

diff --git a/README.rst b/README.rst
index 9b49aca0473c..03987d317470 100644
--- a/README.rst
+++ b/README.rst
@@ -40,9 +40,9 @@ to any symbols.
 Documentation
 -------------
 
-Documentation on how to configure Hawkmoth and write documentation comments,
-with examples, is available in the ``doc`` directory in the source tree,
-obviously in Sphinx format and using the directive extension. Pre-built
+Documentation on how to install and configure Hawkmoth, and write documentation
+comments, with examples, is available in the ``doc`` directory in the source
+tree, obviously in Sphinx format and using the directive extension. Pre-built
 documentation `showcasing what Hawkmoth can do`_ is available at `Read the
 Docs`_.
 
@@ -58,11 +58,8 @@ You can install Hawkmoth from PyPI_ with::
   pip install hawkmoth
 
 You'll additionally need to install Clang and Python 3 bindings for it through
-your distro's package manager; they are not available via PyPI. You may also
-need to set ``LD_LIBRARY_PATH`` so that the Clang library can be found. For
-example::
-
-  export LD_LIBRARY_PATH=$(llvm-config --libdir)
+your distro's package manager; they are not available via PyPI. For further
+details, see the documentation.
 
 Alternatively, installation packages are available for:
 
diff --git a/doc/extension.rst b/doc/extension.rst
index c5d477822712..6ef6b8538f0c 100644
--- a/doc/extension.rst
+++ b/doc/extension.rst
@@ -12,8 +12,11 @@ For this to work, the documentation comments must of course 
be written in
 correct reStructuredText. See :ref:`documentation comment syntax <syntax>` for
 details.
 
-Installation
-------------
+See :ref:`installation` on how to install the Hawkmoth package and its
+dependencies.
+
+Usage
+-----
 
 Add ``hawkmoth`` to :data:`sphinx:extensions` in ``conf.py``. Note that
 depending on the packaging and installation directory, this may require
diff --git a/doc/index.rst b/doc/index.rst
index 94b05b7f290f..5fe6113b198c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,8 +14,9 @@ Please see the `Hawkmoth project GitHub page`_ (or README.rst 
in the source
 repository) for information on how to obtain, install, and contribute to
 Hawkmoth, as well as how to contact the developers.
 
-Read on for information about Hawkmoth usage; how to configure and use the
-extension and how to write documentation comments, with examples.
+Read on for information about Hawkmoth installation details and usage; how to
+configure and use the extension and how to write documentation comments, with
+examples.
 
 .. _Sphinx: http://www.sphinx-doc.org
 
@@ -30,6 +31,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   installation
    extension
    syntax
    examples
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 000000000000..1f7e80f247c4
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,89 @@
+.. _installation:
+
+Installation
+============
+
+You can install the Hawkmoth Python package and most of its dependencies from
+PyPI_ with:
+
+.. code-block:: shell
+
+  pip install hawkmoth
+
+However, you'll also need to install Clang and Clang Python Bindings through
+your distro's package manager; they are not available via PyPI_. This is
+typically the biggest hurdle in getting your Hawkmoth setup to work.
+
+.. _PyPI: https://pypi.org/project/hawkmoth/
+
+Clang Distro Install
+--------------------
+
+This step is necessarily distro specific.
+
+For example, in Debian Bullseye:
+
+.. code-block:: shell
+
+   apt install python3-clang
+
+Clang Python Bindings
+---------------------
+
+There are **unofficial** Clang Python Bindings available in PyPI_. They may be
+helpful in some scenarios (for example Debian Buster not packaging Clang Python
+Bindings for Python 3 at all), but they will not include the binary
+``libclang``, and the provided Python Bindings might not be compatible with the
+library provided in your system.
+
+If the Clang Python Bindings are unable to find ``libclang``, for whatever
+reason, there are some tricks to try:
+
+* Set the library path in shell:
+
+  .. code-block:: shell
+
+     export LD_LIBRARY_PATH=$(llvm-config --libdir)
+
+* Set the library path in ``conf.py``:
+
+  .. code-block:: python
+
+     from clang.cindex import Config
+     Config.set_library_path('/path/to/clang')
+
+* Set the library name in ``conf.py``, possibly combined with
+  ``LD_LIBRARY_PATH``:
+
+  .. code-block:: python
+
+     from clang.cindex import Config
+     Config.set_library_file('libclang.so')
+
+* Set the library name with full path in ``conf.py``:
+
+  .. code-block:: python
+
+     from clang.cindex import Config
+     Config.set_library_file('/path/to/clang/libclang.so')
+
+Virtual Environment
+-------------------
+
+If you're installing Hawkmoth in a Python virtual environment, use the
+``--system-site-packages`` option when creating the virtual environment to make
+the distro Clang package available to the virtual environment. For example:
+
+.. code-block:: shell
+
+   python3 -m venv --system-site-packages .venv
+
+Docker
+------
+
+It's also possible to set up a Docker container to run Sphinx with
+Hawkmoth. There are no official images for this at this time, but please have a
+look at the ``Dockerfile`` in the `Hawkmoth source repository`_ for a starting
+point; the file is used for testing during Hawkmoth development.
+
+.. _Hawkmoth source repository: https://github.com/jnikula/hawkmoth
-- 
2.29.2


Other related posts:

  • » [hawkmoth] [PATCH 5/5] doc: add detailed installation instructions - Jani Nikula