mirror of
https://github.com/calibrain/shelfmark.git
synced 2026-11-14 23:18:36 +00:00
splitsec2
e273e7b0ed
This is the biggest of the docs batch, and this time I don't think it was my PRs that caused it. The plugin guides fell behind as the plugin API changed over several releases, and nobody updated them along the way. Same arrangement as the others: Claude compared the guides to the code and wrote the changes, so another human look before this merges would be good. Someone who knows the plugin API well would catch things I would not. These are the parts I would read first: the search plan table, the `SourceUnavailableError` advice in the error handling section, and the `locating` status row. What was wrong and is now fixed, all checked against the code: Release sources guide - `search` takes `(book, plan, *, expand_search, content_type)`. Every sample had the old one-argument signature, so a source written from the guide raised a TypeError on its first search. There is now a short table of the search plan fields. - A source is registered by adding its module to `_BUILTIN_SOURCE_MODULES`. The guide said to add an import at the bottom of `__init__.py`. - `get_column_config` is an instance method, not a classmethod, and `ColumnRenderType.SEEDERS` does not exist (the real members are listed). - `download` can return a `HandoffResult`. `list_available_sources` lists every source with an `enabled` flag, it does not filter. - `group="sources"` is gone, since only `direct_download` and `metadata_providers` exist. - Field lists for `Release`, `DownloadTask`, `BookMetadata`, `ColumnSchema` and `ReleaseColumnConfig` are brought up to date, with the protocol enum and the `locating` status. - The optional hooks that were not mentioned (`post_process_cleanup`, `build_retry_resolution_fields`, `list_authors`, `seed_complaints`, `get_record`, `get_destination_override`, `search_results_are_releases`) are documented. Plugin settings guide - The examples imported from `shelfmark.metadata_providers.base` and `shelfmark.release_sources.base`, which do not exist. The metadata example also skipped the abstract `search_by_isbn` and the kwargs factory. - Value priority now starts with the environment variable, and `search_mode` is listed next to `general` as using `settings.json`. The `metadata_providers` group order is 12, not 50. - Documented `TagListField`, `OrderableListField`, `TableField`, `env_var`, `env_supported`, `user_overridable`, `universal_only`, `filter_by_field`, `register_on_save` and the `current_values` argument for action callbacks. Also in here: `docs/dev/index.md` was a TODO stub and is now a short index linked from `docs/index.md`, a dead link in the metadata providers README is fixed, and the README table gains Databáze knih and Moly.hu. To check the samples were not just plausible, I ran the quick start and the full BookNet example against the real registry. Both register, instantiate and return their column config. The old BookNet example failed on import with a NameError, because the Test Connection callback was defined below the settings function that references it. The decorator calls that function straight away, so both settings snippets now define the callback first.
8 lines
403 B
Markdown
8 lines
403 B
Markdown
# Developer Documentation
|
|
|
|
Guides for adding to Shelfmark.
|
|
|
|
- [Release Sources Plugin Guide](release-sources-plugin-guide.md): add a source that searches for releases and a handler that downloads them
|
|
- [Plugin Settings Guide](plugin-settings.md): add settings tabs and fields for a plugin to the Settings UI
|
|
- [Metadata Providers](../../shelfmark/metadata_providers/README.md): add a metadata provider
|