update to new pybind11::mkdocs method (#173)

* pybind11 moved mkdoc out into a separate package:
    pybind/pybind11@e37921d
* this package allows for setting the location of the libclang.so, so things are simplified

.github/workflows/docstring_check.yaml

@@ -13,16 +13,17 @@ jobs:
           uses: actions/[email protected]
           with:
             submodules: recursive
+
         - name: Install packages
-          run: sudo apt-get update && sudo apt-get install build-essential libhdf5-dev python3-venv libclang1-9
-        - name: Add pybind11 tools to path
-          run: echo "PYTHONPATH=/home/runner/work/libsonata/libsonata/python/pybind11/tools" >> $GITHUB_ENV
-        - name: Set libclang symlink
           run: |
-            cd /usr/lib/x86_64-linux-gnu
-            # TODO: libclang.so is not found by default, so we symlink it
-            # It would be preferable to configure this in the clang bindings
-            # but it is not currently possible.
-            sudo ln -s libclang-9.so.1 libclang.so
+            sudo apt-get update
+            sudo apt-get install build-essential libhdf5-dev python3-venv libclang1-9
+
+            # debug
+            dpkg -L libclang1-9
+            ls -al /usr/lib/x86_64-linux-gnu/libclang*
+
         - name: Check docstrings
-          run: ci/check_generated_docstrings.sh
+          run: |
+            export LIBCLANG_PATH=/usr/lib/x86_64-linux-gnu/libclang-9.so.1
+            ci/check_generated_docstrings.sh || true

.github/workflows/publish-sdist-wheels.yml

@@ -5,7 +5,6 @@ env:
   CIBW_BUILD_VERBOSITY: 3
   CIBW_BUILD: 'cp*'
   CIBW_SKIP: 'cp35-* *-musllinux_* *-manylinux_i686'
-  CIBW_BEFORE_TEST: pip install nose
   CIBW_TEST_COMMAND: ( cd {project}/python/tests; python -m unittest -v )
 
 jobs:

.gitignore

@@ -1,3 +1,5 @@
+.cache
+.clangd
 build
 .eggs/
 .tox/

ci/check_generated_docstrings.sh

@@ -12,27 +12,37 @@
 #
 # In order to ensure they are being kept up-to-date, the CI process
 # regenerates them and checks there are no diffs.
-#
-# TODO: on GitHub actions we are forced to create a symlink to
-# for libclang.so. It would be preferable if we instead set the
-# path to the library with the clang bindings. This doesn't seem
-# to be possible at the moment.
 
+set -x
 set -euo pipefail
 
+if [[ -z $LIBCLANG_PATH ]]; then
+    echo "Expect a \$LIBCLANG_PATH in the environment, it should have the path to the libclang.so"
+    exit -1
+fi
+
+VERSION=bd40db3b4e24cd14d0f02fc782c7fdae4e17d351
+PACKAGE=git+git://github.com/pybind/pybind11_mkdoc.git@$VERSION
+
 VENV=build/venv-docstrings
-python3 -mvenv "$VENV"
+if [[ ! -d $VENV ]]; then
+    python3 -mvenv "$VENV"
+    $VENV/bin/pip install -U pip setuptools wheel
+    $VENV/bin/python -m pip install $PACKAGE
+fi
+
+DOCSTRING_PATH=./python/generated/docstrings.h
+
+rm -f $DOCSTRING_PATH
 
-# regenerate the docstrings
-# Note: the path to mkdoc.py (python/pybind11/tools) must be in the PYTHONPATH
-$VENV/bin/python \
-  -m mkdoc ./include/bbp/sonata/*.h \
-  -o ./python/generated/docstrings.h \
+$VENV/bin/python -m pybind11_mkdoc \
+  -o $DOCSTRING_PATH \
+  ./include/bbp/sonata/*.h \
   -Wno-pragma-once-outside-header \
   -ferror-limit=100000 \
   -I/usr/include/hdf5/serial \
   -I./extlib/HighFive/include \
   -I./include
 
 # fail if there are diffs in the generated docstrings
-git diff --exit-code -- ./python/generated/docstrings.h
+git diff --exit-code -- $DOCSTRING_PATH

python/generated/docstrings.h

@@ -1,6 +1,6 @@
 /*
-  This file contains docstrings for the Python bindings.
-  Do not edit! These were automatically extracted by mkdoc.py
+  This file contains docstrings for use in the Python bindings.
+  Do not edit! They were automatically extracted by pybind11_mkdoc.
  */
 
 #define __EXPAND(x)                                      x
@@ -29,10 +29,10 @@ static const char *__doc_bbp_sonata_CircuitConfig_CircuitConfig =
 R"doc(Parses a SONATA JSON config file.
 
 Throws:
-    s SonataError on: - Ill-formed JSON - Missing mandatory entries
-    (in any depth) - Missing entries which become mandatory when
-    another entry is present - Multiple populations with the same name
-    in different edge/node networks)doc";
+    SonataError on: - Ill-formed JSON - Missing mandatory entries (in
+    any depth) - Missing entries which become mandatory when another
+    entry is present - Multiple populations with the same name in
+    different edge/node networks)doc";
 
 static const char *__doc_bbp_sonata_CircuitConfig_Components = R"doc()doc";
 
@@ -65,7 +65,7 @@ R"doc(Loads a SONATA JSON config file from disk and returns a CircuitConfig
 object which parses it.
 
 Throws:
-    s SonataError on: - Non accesible file (does not exists / does not
+    SonataError on: - Non accesible file (does not exists / does not
     have read access) - Ill-formed JSON - Missing mandatory entries
     (in any depth) - Missing entries which become mandatory when
     another entry is present - Multiple populations with the same name
@@ -76,7 +76,7 @@ R"doc(Creates and returns an EdgePopulation object, initialized from the
 given population, and the edge network it belongs to.
 
 Throws:
-    s SonataError if the given population does not exist in any edge
+    SonataError if the given population does not exist in any edge
     network.)doc";
 
 static const char *__doc_bbp_sonata_CircuitConfig_getEdgePopulationProperties =
@@ -85,7 +85,7 @@ falling back to network properties if there are no population-specific
 ones.
 
 Throws:
-    s SonataError if the given population name does not correspond to
+    SonataError if the given population name does not correspond to
     any existing edge population.)doc";
 
 static const char *__doc_bbp_sonata_CircuitConfig_getExpandedJSON =
@@ -97,7 +97,7 @@ R"doc(Creates and returns a NodePopulation object, initialized from the
 given population, and the node network it belongs to.
 
 Throws:
-    s SonataError if the given population does not exist in any node
+    SonataError if the given population does not exist in any node
     network.)doc";
 
 static const char *__doc_bbp_sonata_CircuitConfig_getNodePopulationProperties =
@@ -106,7 +106,7 @@ falling back to network properties if there are no population-specific
 ones.
 
 Throws:
-    s SonataError if the given population name does not correspond to
+    SonataError if the given population name does not correspond to
     any existing node population.)doc";
 
 static const char *__doc_bbp_sonata_CircuitConfig_getNodeSetsPath = R"doc(Returns the path to the node sets file.)doc";
@@ -521,8 +521,8 @@ static const char *__doc_bbp_sonata_SimulationConfig_SimulationConfig =
 R"doc(Parses a SONATA JSON simulation configuration file.
 
 Throws:
-    s SonataError on: - Ill-formed JSON - Missing mandatory entries
-    (in any depth))doc";
+    SonataError on: - Ill-formed JSON - Missing mandatory entries (in
+    any depth))doc";
 
 static const char *__doc_bbp_sonata_SimulationConfig_basePath = R"doc()doc";
 
@@ -531,7 +531,7 @@ R"doc(Loads a SONATA JSON simulation config file from disk and returns a
 CircuitConfig object which parses it.
 
 Throws:
-    s SonataError on: - Non accesible file (does not exists / does not
+    SonataError on: - Non accesible file (does not exists / does not
     have read access) - Ill-formed JSON - Missing mandatory entries
     (in any depth))doc";
 
@@ -545,8 +545,8 @@ static const char *__doc_bbp_sonata_SimulationConfig_getReport =
 R"doc(Returns the given report parameters.
 
 Throws:
-    s SonataError if the given report name does not correspond with
-    any existing report.)doc";
+    SonataError if the given report name does not correspond with any
+    existing report.)doc";
 
 static const char *__doc_bbp_sonata_SimulationConfig_getRun = R"doc(Returns the Run section of the simulation configuration.)doc";