search

nedbat / scriv

Changelog management tool
https://scriv.readthedocs.io
Apache License 2.0
260 stars 29 forks source link

Provide a supported API #12

Open nedbat opened 4 years ago

nedbat commented 4 years ago

From https://twitter.com/webKnjaZ/status/1308027546697641984

webknjaz commented 4 years ago

So the things I needed from Towncrier in the past, of the top of my head, were: 1) Getting all the settings, including note categories and fragment paths (in order to come up with a regex for checking added files in PR diffs) 2) Rendering the unpublished version notes draft (for inclusion in Sphinx-based docs) and passing a custom string for the version used in the notes title 3) Figuring out whether any of those fragments are actually present (this one was for supporting complicated edge cases in the Sphinx's caching mechanism)

But rather than exposing an API endpoint each time it's necessary, I suggest having an architecture that allows having API (almost) always exposed by having a separate layer that the CLI would use. This way, the main consumer of that API would be the CLI, and everything that CLI offers would be available automatically:

[CLI] -> [public API] -> [private APIs in the project core]
              ^
              |
      /----------------\
      | other  projects |
      | importing scriv |
      \----------------/

This would probably mean moving logic from click-decorated functions into separate ones.

nedbat commented 3 years ago

I'm coming back to thinking about this. I don't understand this one:

Figuring out whether any of those fragments are actually present

The fragments are just files in a directory. Do you mean, figure out what fragments are present?

nedbat commented 3 years ago

I've refactored to create a sketch of an API in pull request #28. Take a look and let me know what you think.

webknjaz commented 3 years ago

The fragments are just files in a directory. Do you mean, figure out what fragments are present?

Yes, even better: check if the fragments are present and valid. In the context of linting checks in pull requests, it's usually important to figure out if a new fragment has been added, not that some files are present in the dir (they can be old).

nedbat commented 3 years ago

Yes, even better: check if the fragments are present and valid. In the context of linting checks in pull requests, it's usually important to figure out if a new fragment has been added, not that some files are present in the dir (they can be old).

Thanks. I've written a new issue for that feature: Provide a "check" command.

nedbat commented 3 years ago

Version 0.11.0 has an (undocumented) API now. Let me know if you try it.