From 83c2ca831fccba58b026266adb63a468411d5c93 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Tue, 31 Dec 2024 19:47:25 -0800 Subject: [PATCH 1/2] docs: renders licenses of deps in tables Also generates tables for the dependencies of the bindings using the `cargo tree` command. --- docs/license_gen.py | 87 +++++++++++++++++++++++++++++---------------- 1 file changed, 56 insertions(+), 31 deletions(-) diff --git a/docs/license_gen.py b/docs/license_gen.py index 2df5110..19d6731 100644 --- a/docs/license_gen.py +++ b/docs/license_gen.py @@ -1,3 +1,4 @@ +import re import mkdocs_gen_files from subprocess import run @@ -10,61 +11,85 @@ [MPL-2.0]: https://choosealicense.com/licenses/mpl-2.0 """ -OPTIONAL_DEPS = """## Optional dependencies +TABLE_HEADER = "| Dependency | License |\n|:------------|:-------|\n" + +OPTIONAL_DEPS = f"""## Optional dependencies The following are conditionally included in binaries (using the `openssl-vendored` feature on a case-by-case basis) because it is a dependency of [git2](https://crates.io/crates/git2): -- [openssl](https://crates.io/crates/openssl): Licensed under [Apache-2.0]. -- [openssl-probe](https://crates.io/crates/openssl-probe): - Dual-licensed under [Apache-2.0] or [MIT]. +{TABLE_HEADER}\ +| [openssl](https://crates.io/crates/openssl) | [Apache-2.0] | +| [openssl-probe](https://crates.io/crates/openssl-probe) | [MIT] OR [Apache-2.0] | """ -BINDING_DEPS = """## Bindings' dependencies +PY_BINDING_HEADER = f"""## Bindings' dependencies -The python binding uses +### Python binding -- [pyo3](https://crates.io/crates/pyo3): - Dual-licensed under [Apache-2.0] or [MIT]. +{TABLE_HEADER}""" -The node binding uses +JS_BINDING_HEADER = f"""### Node.js binding -- [napi](https://crates.io/crates/napi): Licensed under [MIT] -- [napi-derive](https://crates.io/crates/napi-derive): Licensed under [MIT] -""" +{TABLE_HEADER}""" -with mkdocs_gen_files.open(FILENAME, "w") as io_doc: - print(INTRO, file=io_doc) - output = run( - [ +SELF_DEP = re.compile(r"(\| \[cpp-linter v[0-9.]+[^\s]*)[^\]]+(\]\(.*)$") + + +class TreeGetter: + def __init__(self): + self.args = [ "cargo", "tree", "-f", - r"[{p}]({r}): Licensed under {l}", + r"| [{p}]({r}) | {l} |", "-e", "normal", "-p", "cpp-linter", "--depth", "1", - ], - capture_output=True, - check=True, - ) - doc = "\n".join( - [ - "- " - + line[3:] - .replace(" MIT", " [MIT]") - .replace(" Apache-2.0", " [Apache-2.0]") - .replace(" MPL-2.0", " [MPL-2.0]") - for line in output.stdout.decode(encoding="utf-8").splitlines()[1:] ] - ) + + def package(self, value: str) -> None: + self.args[7] = value + + def get_output(self) -> str: + output = run( + self.args, + capture_output=True, + check=True, + ) + result = [] + for line in output.stdout.decode(encoding="utf-8").splitlines()[1:]: + dep = ( + line[3:] + .replace(" MIT", " [MIT]") + .replace(" Apache-2.0", " [Apache-2.0]") + .replace(" MPL-2.0", " [MPL-2.0]") + .strip() + ) + self_match = SELF_DEP.match(dep) + if self_match is not None: + dep = SELF_DEP.sub(r"\1\2", dep) + result.append(dep) + return "\n".join(result) + + +with mkdocs_gen_files.open(FILENAME, "w") as io_doc: + tg = TreeGetter() + print(INTRO, file=io_doc) + doc = TABLE_HEADER + doc += tg.get_output() # print(doc) print(doc, file=io_doc) print(f"\n{OPTIONAL_DEPS}\n", file=io_doc) - print(f"\n{BINDING_DEPS}\n", file=io_doc) + tg.package("cpp-linter-py") + doc = tg.get_output() + print(f"\n{PY_BINDING_HEADER}{doc}", file=io_doc) + tg.package("cpp-linter-js") + doc = tg.get_output() + print(f"\n{JS_BINDING_HEADER}{doc}", file=io_doc) mkdocs_gen_files.set_edit_path(FILENAME, "license-gen.py") From 059eae27cb6c468efd3f97c7119d07e57346bbfb Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Wed, 1 Jan 2025 16:14:05 -0800 Subject: [PATCH 2/2] typo in node binding README --- bindings/node/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/bindings/node/README.md b/bindings/node/README.md index 739777a..1b69441 100644 --- a/bindings/node/README.md +++ b/bindings/node/README.md @@ -53,15 +53,15 @@ This script runs a simple test to ensure the native module was built correctly. | Name | Description | |-----:|:------------| | `__test__` | The location of the unit test(s). | -| `npm` | The required metadata for publishing platform-specific packages to npm. | +| `npm` | The required metadata for publishing platform-specific binary packages to npm. | | `src` | The location for all rust sources related to binding the cpp-linter library. | | `build.rs` | The cargo-specific build script used when compiling the binding. | | `Cargo.toml` | Metadata about the binding's rust package (which _is not_ intended to be published to crates.io). | -| `package.json` | Metadata about the npm package (platform agnostic). | +| `package.json` | Metadata about the npm package (platform agnostic - no binary). | | `cli.js` | The executable script invoked as a Command Line Interface. | -| `index.d.ts` | The generated TypeScript typing info the describes the exposing functionality in the built native module. | -| `index.js` | The generated script that delegates which platform-specific package to import. | -| `cpp-linter.x-y-z.node` | Then native module built for a specific platform (where `x-y-z` denotes the platform's name using compilation target). | +| `index.d.ts` | The generated TypeScript typing and doc info that describes the exposed API in the built native module. | +| `index.js` | The generated script that delegates which native binary (platform-specific package or dev build) to import. | +| `cpp-linter.x-y-z.node` | The native module built for a specific platform (where `x-y-z` denotes the platform's name using the compilation target). | Hidden files and folders are not described in the table above. If they are not ignored by a gitignore specification, then they should be considered