From 763a9212d587f2201a48d6007dece331f295dbca Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Wed, 28 Jun 2023 10:53:19 +0200 Subject: [PATCH 1/3] Make generated file use valid C++ identifiers * according to https://en.cppreference.com/w/cpp/language/identifiers * identifiers with a double underscore anywhere; * identifiers that begin with an underscore followed by an uppercase letter; * in the global namespace, identifiers that begin with an underscore. * clang w/ `-Weverything` is including `-Wreserved-id-macro`, which fails with the current macro naming scheme. * cleaned up tests a bit --- pybind11_mkdoc/mkdoc_lib.py | 27 +++++++++++------------ tests/sample_header_test.py | 43 ++++++++++++++++--------------------- 2 files changed, 32 insertions(+), 38 deletions(-) diff --git a/pybind11_mkdoc/mkdoc_lib.py b/pybind11_mkdoc/mkdoc_lib.py index 0d591d4..37238ca 100755 --- a/pybind11_mkdoc/mkdoc_lib.py +++ b/pybind11_mkdoc/mkdoc_lib.py @@ -82,7 +82,7 @@ def sanitize_name(name): name = re.sub('<.*>', '', name) name = ''.join([ch if ch.isalnum() else '_' for ch in name]) name = re.sub('_$', '', re.sub('_+', '_', name)) - return '__doc_' + name + return 'mkd_doc_' + name def process_comment(comment): @@ -389,19 +389,18 @@ def write_header(comments, out_file=sys.stdout): Do not edit! They were automatically extracted by pybind11_mkdoc. */ -#define __EXPAND(x) x -#define __COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...) COUNT -#define __VA_SIZE(...) __EXPAND(__COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0)) -#define __CAT1(a, b) a ## b -#define __CAT2(a, b) __CAT1(a, b) -#define __DOC1(n1) __doc_##n1 -#define __DOC2(n1, n2) __doc_##n1##_##n2 -#define __DOC3(n1, n2, n3) __doc_##n1##_##n2##_##n3 -#define __DOC4(n1, n2, n3, n4) __doc_##n1##_##n2##_##n3##_##n4 -#define __DOC5(n1, n2, n3, n4, n5) __doc_##n1##_##n2##_##n3##_##n4##_##n5 -#define __DOC6(n1, n2, n3, n4, n5, n6) __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6 -#define __DOC7(n1, n2, n3, n4, n5, n6, n7) __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7 -#define DOC(...) __EXPAND(__EXPAND(__CAT2(__DOC, __VA_SIZE(__VA_ARGS__)))(__VA_ARGS__)) +#define MKD_EXPAND(x) x +#define MKD_COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...) COUNT +#define MKD_VA_SIZE(...) MKD_EXPAND(MKD_COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0)) +#define MKD_CAT1(a, b) a ## b +#define MKD_CAT2(a, b) MKD_CAT1(a, b) +#define MKD_DOC1(n1) mkd_doc_##n1 +#define MKD_DOC2(n1, n2) mkd_doc_##n1##_##n2 +#define MKD_DOC3(n1, n2, n3) mkd_doc_##n1##_##n2##_##n3 +#define MKD_DOC4(n1, n2, n3, n4) mkd_doc_##n1##_##n2##_##n3##_##n4 +#define MKD_DOC5(n1, n2, n3, n4, n5) mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5 +#define MKD_DOC7(n1, n2, n3, n4, n5, n6, n7) mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7 +#define DOC(...) MKD_EXPAND(MKD_EXPAND(MKD_CAT2(MKD_DOC, MKD_VA_SIZE(__VA_ARGS__)))(__VA_ARGS__)) #if defined(__GNUG__) #pragma GCC diagnostic push diff --git a/tests/sample_header_test.py b/tests/sample_header_test.py index e93634c..08d8d20 100644 --- a/tests/sample_header_test.py +++ b/tests/sample_header_test.py @@ -1,43 +1,39 @@ -import collections import os -import time -import sysconfig import sys -import pytest - import pybind11_mkdoc DIR = os.path.abspath(os.path.dirname(__file__)) -def test_generate_headers(capsys): +def test_generate_headers(capsys, tmp_path): comments = pybind11_mkdoc.mkdoc_lib.extract_all([os.path.join(DIR, "sample_header_docs", "sample_header.h")]) - pybind11_mkdoc.mkdoc_lib.write_header(comments, sys.stdout) + output = tmp_path / "docs.h" + with output.open("w") as fd: + pybind11_mkdoc.mkdoc_lib.write_header(comments, fd) res = capsys.readouterr() assert "warning" not in res.err assert "error" not in res.err - assert res.out == """\ + assert output.read_text() == """\ /* This file contains docstrings for use in the Python bindings. Do not edit! They were automatically extracted by pybind11_mkdoc. */ -#define __EXPAND(x) x -#define __COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...) COUNT -#define __VA_SIZE(...) __EXPAND(__COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0)) -#define __CAT1(a, b) a ## b -#define __CAT2(a, b) __CAT1(a, b) -#define __DOC1(n1) __doc_##n1 -#define __DOC2(n1, n2) __doc_##n1##_##n2 -#define __DOC3(n1, n2, n3) __doc_##n1##_##n2##_##n3 -#define __DOC4(n1, n2, n3, n4) __doc_##n1##_##n2##_##n3##_##n4 -#define __DOC5(n1, n2, n3, n4, n5) __doc_##n1##_##n2##_##n3##_##n4##_##n5 -#define __DOC6(n1, n2, n3, n4, n5, n6) __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6 -#define __DOC7(n1, n2, n3, n4, n5, n6, n7) __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7 -#define DOC(...) __EXPAND(__EXPAND(__CAT2(__DOC, __VA_SIZE(__VA_ARGS__)))(__VA_ARGS__)) +#define MKD_EXPAND(x) x +#define MKD_COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...) COUNT +#define MKD_VA_SIZE(...) MKD_EXPAND(MKD_COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0)) +#define MKD_CAT1(a, b) a ## b +#define MKD_CAT2(a, b) MKD_CAT1(a, b) +#define MKD_DOC1(n1) mkd_doc_##n1 +#define MKD_DOC2(n1, n2) mkd_doc_##n1##_##n2 +#define MKD_DOC3(n1, n2, n3) mkd_doc_##n1##_##n2##_##n3 +#define MKD_DOC4(n1, n2, n3, n4) mkd_doc_##n1##_##n2##_##n3##_##n4 +#define MKD_DOC5(n1, n2, n3, n4, n5) mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5 +#define MKD_DOC7(n1, n2, n3, n4, n5, n6, n7) mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7 +#define DOC(...) MKD_EXPAND(MKD_EXPAND(MKD_CAT2(MKD_DOC, MKD_VA_SIZE(__VA_ARGS__)))(__VA_ARGS__)) #if defined(__GNUG__) #pragma GCC diagnostic push @@ -45,11 +41,11 @@ def test_generate_headers(capsys): #endif -static const char *__doc_RootLevelSymbol = +static const char *mkd_doc_RootLevelSymbol = R"doc(Root-level symbol. Magna fermentum iaculis eu non diam phasellus vestibulum.)doc"; -static const char *__doc_drake_MidLevelSymbol = +static const char *mkd_doc_drake_MidLevelSymbol = R"doc(1. Begin first ordered list element. Rutrum quisque non tellus orci ac auctor. End first ordered list element. 2. Begin second ordered list element. Ipsum faucibus vitae aliquet nec. Ligula ullamcorper @@ -66,4 +62,3 @@ def test_generate_headers(capsys): #endif """ - From 51e445dd2538ab0e26dfa6f56a4662f785860aa4 Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Wed, 28 Jun 2023 14:12:06 +0200 Subject: [PATCH 2/3] check `comments` early --- tests/sample_header_test.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tests/sample_header_test.py b/tests/sample_header_test.py index 08d8d20..dc12ff4 100644 --- a/tests/sample_header_test.py +++ b/tests/sample_header_test.py @@ -7,7 +7,11 @@ def test_generate_headers(capsys, tmp_path): - comments = pybind11_mkdoc.mkdoc_lib.extract_all([os.path.join(DIR, "sample_header_docs", "sample_header.h")]) + comments = pybind11_mkdoc.mkdoc_lib.extract_all( + [os.path.join(DIR, "sample_header_docs", "sample_header.h")] + ) + assert ['mkd_doc_RootLevelSymbol', 'mkd_doc_drake_MidLevelSymbol'] == [c[0] for c in comments] + output = tmp_path / "docs.h" with output.open("w") as fd: pybind11_mkdoc.mkdoc_lib.write_header(comments, fd) From 8a67866c21215e78166c7a548d5d44d1de568fc8 Mon Sep 17 00:00:00 2001 From: Mike Gevaert Date: Wed, 28 Jun 2023 14:44:17 +0200 Subject: [PATCH 3/3] Pin clang==14.0.6 --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 177c93d..d74452f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,7 +30,7 @@ jobs: python-version: ${{ matrix.python-version }} - name: Install package - run: python -m pip install .[test] + run: python -m pip install .[test] "clang==14.0.6" - name: Test package run: python -m pytest --forked