Merge pull request #6 from second-ed/dev

v0.2.0

Author: second-ed

.github/workflows/publish.yaml

@@ -1,8 +1,6 @@
 name: Build & maybe upload PyPI package
 'on':
   push:
-    branches:
-    - main
     tags:
     - '*'
   pull_request:

.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+repos:
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.5.26
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-yaml
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.4
+    hooks:
+    - id: ruff
+      args: [ --fix ]
+    - id: ruff-format
+  - repo: local
+    hooks:
+      - id: build
+        name: build
+        entry: cargo build --verbose
+        language: rust
+        pass_filenames: false
+      - id: fmt
+        name: fmt
+        entry: cargo fmt --all -- --check
+        language: rust
+        pass_filenames: false
+      - id: test
+        name: test
+        entry: cargo test
+        language: rust
+        pass_filenames: false
+      - id: clippy
+        name: clippy
+        entry: cargo clippy
+        language: rust
+        pass_filenames: false
+      - id: repo-map
+        name: repo_map
+        entry: uv
+        language: system
+        pass_filenames: false
+        args:
+          - run
+          - -m
+          - repo_mapper
+          - --repo-root
+          - .
+          - --readme-path
+          - ./README.md
+          - --gitignore-path
+          - ./.gitignore
+          - --allowed-exts
+          - py,rs,md,yaml,toml,lock
+          - --ignore-dirs
+          - .venv,target,.git
+          # - --ignore-hidden

Cargo.lock

@@ -1,16 +1,17 @@
 [package]
 name = "readme-update"
-version = "0.1.2"
+version = "0.2.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [lib]
 name = "readme_update"
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 colored = "3.0.0"
 pyo3 = "0.25.0"
 rayon = "1.10.0"
 regex = "1.11.1"
+test-case = "3.3.1"
 walkdir = "2.5.0"

Cargo.toml

@@ -1,4 +1,7 @@
-# Tired of updating documentation?
+# readme-update 🦀
+[![PyPI Downloads](https://static.pepy.tech/badge/readme-update)](https://pepy.tech/projects/readme-update)
+
+## Tired of updating documentation?
 This tool updates your `README.md` with a one line description for each of the python scripts in a directory you point it to (and recursively). It adds the text for lines that start with `"Description: "` and `"Link: "`. It ignores any that don't have the description.
 
 The idea is that links should link to higher level documentation (if it exists).
@@ -15,15 +18,18 @@ It will update in place if the `# Scripts` block exists or else it will append i
 | `example1.py` | This is an example file that links to my own github. | [Link](https://github.com/second-ed) |
 | `example2.py` | Some other description. |  |
 | `example3.py` |  | [Link](https://doc.rust-lang.org/book/) |
-| `example_usage.py` |  |  |
 ::
 
-# To install the package
+# Installation
 ```shell
 pip install readme-update
 ```
+Or
+```shell
+uv add readme-update
+```
 
-# Usage 
+# Usage
 Assuming its is run from this location.
 ```shell
 root/
@@ -32,15 +38,58 @@ root/
   README.md
 ```
 
-# example_script.py
-```python
-import readme_update
-from pathlib import Path
+```shell
+uv run -m readme-update \
+--scripts-root "./scripts" \
+--readme-path "./README.md"
+```
+
 
-path = Path(__file__)
+# Args
+| Argument           | Type                  | Required | Default | Description                                          |
+| ------------------ | --------------------- | -------- | ------- | ---------------------------------------------------- |
+| `--scripts-root`      | `str`                 | ✅       |  | Path to the root of the scripts to scan           |
+| `--readme-path`    | `str`                 | ❌       | `'./README.md'` | Path to the README file that will be modified        |
 
-readme_update.py_main(
-    str(path.parent),
-    str(path.parents[1] / "README.md")
-)
+
+# Ret codes
+| RetCode               | int | description           |
+| ----------------------| --- | --------------------- |
+| `NoModification`      | 0   | The Repo Map reflects the current state of the repo. |
+| `ModifiedReadme`      | 1   | The README was updated. |
+| `NoPyFiles`   | 2   | No python files found at the `scripts-root` location. |
+| `FailedParsingFile` | 3   | Failed to read README file  |
+| `FailedToWriteReadme`     | 4   | The given `README.md` path does not match the expected basename. |
+
+
+# Repo map
+```
+├── .github
+│   └── workflows
+│       ├── ci.yaml
+│       └── publish.yaml
+├── python
+│   └── update_readme
+│       ├── __init__.py
+│       └── __main__.py
+├── scripts
+│   ├── example1.py
+│   ├── example2.py
+│   └── example3.py
+├── src
+│   ├── core
+│   │   ├── adapters.rs
+│   │   ├── domain.rs
+│   │   └── mod.rs
+│   ├── api.rs
+│   └── lib.rs
+├── tests
+│   └── integration_tests.rs
+├── .pre-commit-config.yaml
+├── Cargo.lock
+├── Cargo.toml
+├── README.md
+├── pyproject.toml
+└── uv.lock
+::
 ```

README.md

@@ -4,22 +4,33 @@ build-backend = "maturin"
 
 [project]
 name = "readme-update"
-version = "0.1.2"
+version = "0.2.0"
 readme = "README.md"
 requires-python = ">=3.10"
 classifiers = [
     "Programming Language :: Rust",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dynamic = ["version"]
 license = { text = "MIT" }
 dependencies = []
+
 [tool.maturin]
 features = ["pyo3/extension-module"]
+module-name = "readme_update"
+python-source = "python"
+python-packages = ["update_readme"]
+strip = true
 
 [tool.uv]
 # Rebuild package when any rust files change
 cache-keys = [{file = "pyproject.toml"}, {file = "rust/Cargo.toml"}, {file = "**/*.rs"}]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.2.0",
+    "repo-mapper-rs>=0.1.0",
+    "ruff>=0.12.5",
+]
 # Uncomment to build rust code in development mode
-# config-settings = { build-args = '--profile=dev' }
+# config-settings = { build-args = '--profile=dev' }

pyproject.toml

@@ -0,0 +1,22 @@
+import argparse
+import os
+import sys
+import readme_update
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument(
+        "--scripts-root",
+        type=os.path.abspath,
+        required=True,
+        help="Path to the root of the scripts to generate the table for.",
+    )
+    parser.add_argument(
+        "--readme-path",
+        type=os.path.abspath,
+        default="./README.md",
+        help="Path to the readme file.",
+    )
+    args = parser.parse_args()
+    sys.exit(int(readme_update.py_main(args.scripts_root, args.readme_path)))

python/update_readme/__init__.py

@@ -0,0 +1,22 @@
+use crate::core::adapters::RealFileSystem;
+use crate::core::domain::{main, RetCode};
+use pyo3::prelude::*;
+use std::path::Path;
+
+#[pyfunction]
+fn py_main(scripts_root: String, readme_path: String) -> PyResult<i8> {
+    let mut file_sys = RealFileSystem;
+    match main(&mut file_sys, scripts_root, Path::new(&readme_path)) {
+        RetCode::NoModification => Ok(0),
+        RetCode::ModifiedReadme => Ok(1),
+        RetCode::NoPyFiles => Ok(2),
+        RetCode::FailedParsingFile => Ok(3),
+        RetCode::FailedToWriteReadme => Ok(4),
+    }
+}
+
+#[pymodule]
+fn readme_update(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(py_main, m)?)?;
+    Ok(())
+}