Skip to content

README.md

Latest commit

 

History

History
102 lines (85 loc) · 3.68 KB

README.md

File metadata and controls

102 lines (85 loc) · 3.68 KB

readme-update 🦀

PyPI Downloads

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.

You can supply alternative --table-fields to create a table with columns for the provided fields. The --link-fields argument is used to signal which of the --table-fields should be rendered as links like this [Link](this/is/the/link).

The idea is that links should link to higher level documentation (if it exists).

This can be used as a pre-commit for python projects with standalone scripts for specific processes.

It will update in place if the # Scripts block exists or else it will append it to the end of the README.md

example_usage.py shows how to call the script from python.

Here is an example output from the tool:

Scripts

Name Description Link
example1.py This is an example file that links to my own github. Link
example2.py Some other description.
example3.py Link
::

Installation

pip install readme-update

Or

uv add readme-update

Usage

Assuming its is run from this location.

root/
  scripts/
    example_script.py
  README.md
uv run -m update_readme \
--scripts-root "./scripts" \
--readme-path "./README.md"

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
--table-fields list ❌ ["Description", "Link"] Fields to dynamically add to the README.md table.
--link-fields list ❌ ["Link"] Which of the provided table fields should be rendered as links.

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.
InvalidLinkFields 5 The given link_fields are not a subset of the given table_fields.

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
::