Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor: Deprecate BaseCollector and BaseRenderer #413

Merged
merged 1 commit into from Apr 9, 2022

Conversation

pawamoy
Copy link
Member

@pawamoy pawamoy commented Apr 2, 2022

Commit message:

The BaseCollector and BaseRenderer are merged into
the BaseHandler (as mixins for now).
Developers are still able to create collectors
and renderers using these deprecated base classes,
and pass instances of them when creating their handler.

All the methods of the deprecated bases can now
be defined on the BaseHandler subclass itself.
Handlers can then be instantiated by passing
the handler's name, the theme and the optional
custom templates folder name/path.

Reasoning: often times, the renderer and the collector
need to communicate or share data. For example,
the Crystal renderer uses the collector to lookup names
when creating cross-references. The Python handlers
are able to filter members when collecting/returning data,
and need the same members list when rendering,
to order the elements based on that list.

This change is the first of two, where the second change
will deprecate the use of selection and rendering keys
in the YAML options or MkDocs configuration, in favor of
a single options key that both the collection and rendering
process will share.


This change was mentioned in #364.
An example of what this implies for existing handlers: mkdocstrings/python#10
Of course, nothing prevents developers from continuing to split their handler logic in multiple parts/classes/modules:

def collect(self, identifier, config):
    return self._other_class.collect(identifier, config)

The BaseCollector and BaseRenderer are merged into
the BaseHandler (as mixins for now).
Developers are still able to create collectors
and renderers using these deprecated base classes,
and pass instances of them when creating their handler.

All the methods of the deprecated bases can now
be defined on the BaseHandler subclass itself.
Handlers can then be instantiated by passing
the handler's name, the theme and the optional
custom templates folder name/path.

Reasoning: often times, the renderer and the collector
need to communicate or share data. For example,
the Crystal renderer uses the collector to lookup names
when creating cross-references. The Python handlers
are able to filter members when collecting/returning data,
and need the same members list when rendering,
to order the elements based on that list.

This change is the first of two, where the second change
will deprecate the use of `selection` and `rendering` keys
in the YAML options or MkDocs configuration, in favor of
a single `options` key that both the collection and rendering
process will share.
@pawamoy pawamoy merged commit eb822cb into master Apr 9, 2022
@oprypin oprypin requested review from oprypin and removed request for oprypin April 10, 2022 15:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant