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
