Provide a supported API

[nedbat]

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

[webknjaz]

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]

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]

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]

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]

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]

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