clangquill 0.0.3__tar.gz

clangquill-0.0.3/.editorconfig

@@ -0,0 +1,24 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+
+[*.{yaml,yml}]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab

clangquill-0.0.3/.gitattributes

@@ -0,0 +1,5 @@
+src/clangquill/_version.py export-subst
+# Pickle files (for testing) should always have UNIX line endings.
+*.pickle text eol=lf
+* text eol=lf
+*.png binary

clangquill-0.0.3/.gitignore

@@ -0,0 +1,109 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# IDE settings
+.vscode/.idea
+.idea
+
+# hatch-vcs generated version file
+src/clangquill/_version.py

clangquill-0.0.3/.markdown_link_check_config.json

@@ -0,0 +1,8 @@
+{
+    "__comment__": "https://github.com/tcort/markdown-link-check#config-file-format",
+    "ignorePatterns": [
+        {
+            "pattern": "^https://github.com/arup-group"
+        }
+    ]
+}

clangquill-0.0.3/.pre-commit-config.yaml

@@ -0,0 +1,46 @@
+---
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/lyz-code/yamlfix/
+    rev: 1.16.0
+    hooks:
+      - id: yamlfix
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+      - id: ruff-format
+# The markdown-link-check can't access internal or private repos, see
+# .markdown_link_check_config.json on how to exclude more than the
+# github.com/arup-group
+  - repo: https://github.com/tcort/markdown-link-check
+    rev: v3.11.2
+    hooks:
+      - id: markdown-link-check
+        args: [--quiet, --config=.markdown_link_check_config.json]
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.6.26
+    hooks:
+      - id: actionlint
+# this should go last since it will fix line endings broken by other tools
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+    # The pre-commit check on CI detects some whitespace changes if we include .github
+        exclude: .github
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-xml
+      - id: check-json
+      - id: pretty-format-json
+        args: [--autofix, --no-sort-keys, --indent=4]
+        exclude: .*\.ipynb$
+      - id: check-symlinks
+      - id: debug-statements
+      - id: fix-byte-order-marker

clangquill-0.0.3/.readthedocs.yml

@@ -0,0 +1,14 @@
+---
+version: 2
+
+python:
+    version: 3
+    install:
+        - method: pip
+          path: .
+          extra_requirements:
+              - docs
+
+sphinx:
+    builder: html
+    fail_on_warning: true

clangquill-0.0.3/AUTHORS.md

@@ -0,0 +1,4 @@
+Credits
+=======
+
+- René Fritze <rene@fritze.me>

clangquill-0.0.3/CMakeLists.txt

@@ -0,0 +1,47 @@
+cmake_minimum_required(VERSION 3.26...3.29)
+
+project(
+  clangquill
+  LANGUAGES CXX
+  DESCRIPTION "libclang -> Sphinx MyST API-docs generator core")
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# --- Python + nanobind -------------------------------------------------------
+# scikit-build-core puts the right Python here; find nanobind via its pip wheel.
+find_package(Python 3.11 REQUIRED COMPONENTS Interpreter Development.Module)
+
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  OUTPUT_VARIABLE nanobind_ROOT
+  COMMAND_ERROR_IS_FATAL ANY)
+find_package(nanobind CONFIG REQUIRED)
+
+# --- Optional libclang -------------------------------------------------------
+# CLANGQUILL_WITH_LIBCLANG: ON | OFF | AUTO (default). When ON/AUTO and libclang
+# is found, the core links it and CLANGQUILL_HAVE_LIBCLANG is defined. This keeps
+# M1 (build system) independent of the libclang-sourcing spike (#4).
+set(CLANGQUILL_WITH_LIBCLANG "AUTO" CACHE STRING "Link libclang: ON, OFF or AUTO")
+include(cmake/FindLibClang.cmake)
+
+# --- Core extension ----------------------------------------------------------
+nanobind_add_module(
+  _core
+  STABLE_ABI
+  NB_STATIC
+  src/cpp/bindings/module.cpp)
+
+target_include_directories(_core PRIVATE src/cpp)
+
+if(CLANGQUILL_LIBCLANG_FOUND)
+  target_link_libraries(_core PRIVATE clangquill::libclang)
+  target_compile_definitions(_core PRIVATE CLANGQUILL_HAVE_LIBCLANG=1)
+  message(STATUS "clangquill: building WITH libclang")
+else()
+  message(STATUS "clangquill: building WITHOUT libclang (stub backend)")
+endif()
+
+install(TARGETS _core LIBRARY DESTINATION clangquill)

clangquill-0.0.3/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+```{highlight} shell
+
+```
+
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at <https://github.com/renefritze/clangquill/issues>.
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug.
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
+wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+### Write Documentation
+
+clangquill could always use more documentation, whether as part of the
+official clangquill docs, in docstrings, or even on the web in blog posts,
+articles, and such.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at <https://github.com/renefritze/clangquill/issues>.
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up {}`clangquill` for local development.
+
+1. Fork the {}`clangquill` repo on GitHub.
+2. Clone your fork locally:
+
+   ```
+   $ git clone https://github.com/renefritze/clangquill
+   ```
+3. Install your local copy into a virtualenv:
+
+   ```
+   $ cd clangquill/
+   $ python3 -m venv venv
+   $ source venv/bin/activate
+   $ python3 -m pip install .[dev]
+   ```
+4. Create a branch for local development:
+
+   ```
+   $ git checkout -b name-of-your-bugfix-or-feature
+   ```
+
+   Now you can make your changes locally.
+5. Make sure you have pre-commit installed and activated:
+
+   ```
+   $ pre-commit install
+   $ pre-commit run --all-files
+   ```
+
+6. Commit your changes and push your branch to GitHub:
+
+   ```
+   $ git add .
+   $ git commit -m "Your detailed description of your changes."
+   $ git push origin name-of-your-bugfix-or-feature
+   ```
+7. Submit a pull request through the GitHub website.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in README.rst.
+3. The pull request should work for multiple Python versions.
+
+## Tips
+
+To run a subset of tests:
+
+```
+$ pytest tests.test_clangquill
+```
+
+## Deploying
+
+TBD

clangquill-0.0.3/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, René Fritze
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

clangquill-0.0.3/MANIFEST.in

@@ -0,0 +1,15 @@
+include AUTHORS.md
+include CONTRIBUTING.md
+include LICENSE
+include README.md
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include docs *.rst *.md conf.py Makefile make.bat *.jpg *.png *.gif
+
+# The C++ core is needed to build the extension from an sdist.
+include CMakeLists.txt
+recursive-include cmake *.cmake
+recursive-include src/cpp *.cpp *.hpp

clangquill-0.0.3/Makefile

@@ -0,0 +1,20 @@
+#!/usr/bin/env make
+
+# this loads $(ENV_FILE) as both makefile variables and into shell env
+ENV_FILE?=.env
+ifneq ($(wildcard $(ENV_FILE)),)
+include $(ENV_FILE)
+export $(shell sed 's/=.*//' $(ENV_FILE))
+endif
+
+.PHONY:  deps format docs
+
+deps:
+	./dependencies.py
+
+format:
+	ruff format .
+	ruff check --fix .
+
+docs:
+	make -C docs html

clangquill-0.0.3/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.2
+Name: clangquill
+Version: 0.0.3
+Summary: Parse Doxygen-documented C++ with libclang and generate MyST Markdown API docs for Sphinx
+Author-Email: clangquill <rene@fritze.me>
+Classifier: Programming Language :: Python :: 3 :: Only
+Project-URL: Documentation, https://github.com/renefritze/clangquill
+Project-URL: Source, https://github.com/renefritze/clangquill
+Requires-Python: >=3.13
+Requires-Dist: rich
+Requires-Dist: packaging
+Requires-Dist: typer
+Requires-Dist: click
+Provides-Extra: docs
+Requires-Dist: sphinx>=6; extra == "docs"
+Requires-Dist: sphinx-autoapi>=3; extra == "docs"
+Requires-Dist: myst-nb>=0.18; extra == "docs"
+Requires-Dist: furo>=2023.9.10; extra == "docs"
+Provides-Extra: ci
+Requires-Dist: pytest; extra == "ci"
+Requires-Dist: pytest-cov; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: ty; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-pycharm; extra == "dev"
+Requires-Dist: pytest-regressions; extra == "dev"
+Requires-Dist: pytest-datadir; extra == "dev"
+Requires-Dist: clangquill[docs]; extra == "dev"
+Description-Content-Type: text/markdown
+
+clangquill
+=========
+
+
+[![image](https://github.com/renefritze/clangquill/workflows/pytest/badge.svg)](https://github.com/renefritze/clangquill/actions)
+
+
+Parse Doxygen-documented C++ with libclang and generate MyST Markdown API docs for Sphinx
+
+
+Features
+--------
+
+-   TODO
+
+Building from source
+--------------------
+
+`clangquill` ships a compiled C++ core (`clangquill._core`) built with
+[scikit-build-core](https://scikit-build-core.readthedocs.io/), CMake and
+[nanobind](https://nanobind.readthedocs.io/). A standard install builds it:
+
+```console
+$ pip install .
+$ python -c "from clangquill import _core; print(_core.have_libclang())"
+```
+
+The core optionally links **libclang**; when `libclang-dev` (or an LLVM prefix
+via `LibClang_ROOT`) is available at build time the extraction backend is
+enabled. Pass `-DCLANGQUILL_WITH_LIBCLANG=ON` to require it.
+
+After generating your project
+-----------------------------
+
+- setup branch protection+automerge in [github project settings](https://github.com/renefritze/clangquill/settings/branches)
+- request install for the codecov.io app in [github project settings](https://github.com/renefritze/clangquill/settings/installations)
+- configure codecov.io in [codecov.io settings](https://codecov.io/gh/renefritze/clangquill/settings)
+- add the `CODECOV_TOKEN` secret in [github project settings](https://github.com/renefritze/clangquill/settings/secrets/actions)
+
+
+Credits
+-------
+
+This package was created with
+[Cookiecutter](https://github.com/audreyr/cookiecutter) and the
+[renefritze/python_cookiecutter](https://github.com/renefritze/python_cookiecutter)
+project template.

clangquill-0.0.3/README.md

@@ -0,0 +1,47 @@
+clangquill
+=========
+
+
+[![image](https://github.com/renefritze/clangquill/workflows/pytest/badge.svg)](https://github.com/renefritze/clangquill/actions)
+
+
+Parse Doxygen-documented C++ with libclang and generate MyST Markdown API docs for Sphinx
+
+
+Features
+--------
+
+-   TODO
+
+Building from source
+--------------------
+
+`clangquill` ships a compiled C++ core (`clangquill._core`) built with
+[scikit-build-core](https://scikit-build-core.readthedocs.io/), CMake and
+[nanobind](https://nanobind.readthedocs.io/). A standard install builds it:
+
+```console
+$ pip install .
+$ python -c "from clangquill import _core; print(_core.have_libclang())"
+```
+
+The core optionally links **libclang**; when `libclang-dev` (or an LLVM prefix
+via `LibClang_ROOT`) is available at build time the extraction backend is
+enabled. Pass `-DCLANGQUILL_WITH_LIBCLANG=ON` to require it.
+
+After generating your project
+-----------------------------
+
+- setup branch protection+automerge in [github project settings](https://github.com/renefritze/clangquill/settings/branches)
+- request install for the codecov.io app in [github project settings](https://github.com/renefritze/clangquill/settings/installations)
+- configure codecov.io in [codecov.io settings](https://codecov.io/gh/renefritze/clangquill/settings)
+- add the `CODECOV_TOKEN` secret in [github project settings](https://github.com/renefritze/clangquill/settings/secrets/actions)
+
+
+Credits
+-------
+
+This package was created with
+[Cookiecutter](https://github.com/audreyr/cookiecutter) and the
+[renefritze/python_cookiecutter](https://github.com/renefritze/python_cookiecutter)
+project template.

clangquill-0.0.3/cmake/FindLibClang.cmake

@@ -0,0 +1,58 @@
+# Locate libclang (the C API) and expose it as the imported target
+# clangquill::libclang plus the cache variable CLANGQUILL_LIBCLANG_FOUND.
+#
+# Honors CLANGQUILL_WITH_LIBCLANG (ON | OFF | AUTO):
+#   OFF  - never look; build the stub backend.
+#   AUTO - look; build with libclang only if found (default, no hard failure).
+#   ON   - look; fail the configure if it cannot be found.
+#
+# Discovery order: an explicit hint (LibClang_ROOT / llvm-config), then common
+# system locations. The manylinux build wires this to a prebuilt LLVM (see #4).
+
+set(CLANGQUILL_LIBCLANG_FOUND FALSE)
+
+if(CLANGQUILL_WITH_LIBCLANG STREQUAL "OFF")
+  return()
+endif()
+
+# Allow an llvm-config to point us at the right prefix.
+find_program(LLVM_CONFIG_EXECUTABLE NAMES llvm-config llvm-config-18 llvm-config-17)
+if(LLVM_CONFIG_EXECUTABLE)
+  execute_process(
+    COMMAND "${LLVM_CONFIG_EXECUTABLE}" --includedir
+    OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE _llvm_incdir
+    ERROR_QUIET)
+  execute_process(
+    COMMAND "${LLVM_CONFIG_EXECUTABLE}" --libdir
+    OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE _llvm_libdir
+    ERROR_QUIET)
+endif()
+
+find_path(
+  LibClang_INCLUDE_DIR
+  NAMES clang-c/Index.h
+  HINTS ${LibClang_ROOT} ${_llvm_incdir}
+  PATH_SUFFIXES include)
+
+find_library(
+  LibClang_LIBRARY
+  NAMES clang libclang clang-18 clang-17
+  HINTS ${LibClang_ROOT} ${_llvm_libdir}
+  PATH_SUFFIXES lib lib64)
+
+if(LibClang_INCLUDE_DIR AND LibClang_LIBRARY)
+  add_library(clangquill::libclang UNKNOWN IMPORTED)
+  set_target_properties(
+    clangquill::libclang PROPERTIES
+    IMPORTED_LOCATION "${LibClang_LIBRARY}"
+    INTERFACE_INCLUDE_DIRECTORIES "${LibClang_INCLUDE_DIR}")
+  set(CLANGQUILL_LIBCLANG_FOUND TRUE)
+  message(STATUS "clangquill: found libclang at ${LibClang_LIBRARY}")
+elseif(CLANGQUILL_WITH_LIBCLANG STREQUAL "ON")
+  message(
+    FATAL_ERROR
+    "CLANGQUILL_WITH_LIBCLANG=ON but libclang was not found. "
+    "Install libclang-dev or set LibClang_ROOT to an LLVM prefix.")
+else()
+  message(STATUS "clangquill: libclang not found; building stub backend")
+endif()

clangquill-0.0.3/docs/.gitignore

@@ -0,0 +1,2 @@
+autoapi
+examples/example*.csv

clangquill-0.0.3/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -W --keep-going
+SPHINXBUILD   = python -m sphinx
+SPHINXPROJ    = clangquill
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

clangquill-0.0.3/docs/authors.md

@@ -0,0 +1,2 @@
+```{include} ../AUTHORS.md
+```