Add scripts configuration for markdown, syntax, and json modules to be called directly

nathanscain commented 3 months ago

Type of changes

[ ] Bug fix
[x] New feature
[ ] Documentation / docstrings
[ ] Tests
[ ] Other

Checklist

[x] I've run the latest black with default args on new code.
[x] I've updated CHANGELOG.md and CONTRIBUTORS.md where appropriate.
[~] I've added tests for new code.
[x] I accept that @willmcgugan may be pedantic in the code review.

Description

I was trying to use rich's terminal rendering of markdown files earlier today, but the project wasn't using rich so python -m rich.markdown wouldn't work without me editing my virtual environment to include items that weren't listed in my pyproject.toml configuration. Typically I'd solve this by installing the package as a tool that has globally callable commands, but rich doesn't currently export any commands.

This PR adds tool.poetry.scripts entries for each of the 3 directly usable commands (markdown, syntax, and json). This required moving the content currently under if __name__ == "__main__": sections to be under a protected _main method so that both the scripts and module (python -m) entrypoints would execute the same code.

Now users can use uv or pipx to install rich as a tool so that these commands are always available:

uv tool install rich
rich.markdown README.md

I'm open to whatever naming convention you'd prefer. Currently the commands are rich.markdown, rich.syntax, and rich.json to mirror the module entrypoints, but these could also be rich-markdown, rich-syntax, and rich-json (or anything else — the only limiting factors are that they shouldn't have spaces and should be clearly tied to rich since the goal is for them to be installed globally without conflicts.)

The change is documented based on the surrounding style. I wasn't able to test building the documentation due a resolution error within the provided requirements.txt:

ERROR: Cannot install -r requirements.txt (line 2) and alabaster==0.7.12 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested alabaster==0.7.12
    sphinx 7.3.7 depends on alabaster~=0.7.14

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip to attempt to solve the dependency conflict

TomJGooding commented 3 months ago

Isn't this already available using rich-cli?

nathanscain commented 3 months ago

Isn't this already available using rich-cli?

Amazingly, this is the first (at least that I remember) time I'm hearing about rich-cli. Based on a quick look, that looks like what I was needing.

Up to you if you want to keep this or not, but seems like that is the preferred method. What if we just strip away everything except the note on the introduction docs page that explains how you'd run it directly using rich-cli? (Because I've used rich for years and have a few applications that might end up using textualize, but I never knew you had this.)

Textualize / rich