docs(algolia): add custom attributes to backend and core methods #9730
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds 2 custom attributes, one which notes whether the method is part of the core API (not on a backend), the other which holds the name of the backend. We then have an algolia ranking setup where we use the value of `core` (descending) to break ties, so `Table.drop` will show up above `RandomBackend.drop`
We were looking at the `resolved_bases` to find docstrings that were defined in a parent class, but this search only goes up a single level of inheritance. For all of our sql-based backends, this means we only go up to `SQLBackend`, not `BaseBackend`. Manually adding `BaseBackend` to the resolution list fills out a LOT of missing docstrings on the backend docs pages.
gforsyth
added
docs
cpcloud
reviewed
Jul 31, 2024
docs/backends/_utils.py
Outdated
| for base in cls.resolved_bases: | ||
| resolved_bases = cls.resolved_bases | ||
| # If we're a SQLBackend (likely) then also search through to `BaseBackend`` | ||
| if (sqlbackend := resolved_bases[0]).name == "SQLBackend": |
There was a problem hiding this comment.
Is there a more generic fix for this, like altering the lookup code to traverse the class hierarchy?
There was a problem hiding this comment.
Yes, but I think it's upstream in quartodoc. I'm going to take a peak at what's involved
cpcloud
approved these changes
Jul 31, 2024
gforsyth
added a commit
to gforsyth/ibis
that referenced
this pull request
Jul 31, 2024
Follow-up to ibis-project#9730. I fixed adding the parent docstrings in the rendered docs, but those weren't showing up in the search summary on Algolia. They do now.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There are several (mostly linked) improvements here:
Adds 2 custom attributes, one which notes whether the method is part of
the core API (not on a backend), the other which holds the name of the
backend.
We then have an algolia ranking setup where we use the value of
core(descending) to break ties, soTable.dropwill show up aboveRandomBackend.dropBaseBackendfor docstringsThe above fix exposed a bunch of empty docstrings for many backend methods inheriting from a grandparent class object.
We were looking at the
resolved_basesto find docstrings that weredefined in a parent class, but this search only goes up a single level
of inheritance. For all of our sql-based backends, this means we only
go up to
SQLBackend, notBaseBackend.Manually adding
BaseBackendto the resolution list fills out a LOT ofmissing docstrings on the backend docs pages.
Having done that, we were now successfully rendering schema methods that are deprecated and we don't want to advertise, so I turned that off.
It was possible for these resolved_bases to get duplicated, so I stopped that.
A lot of algolia config happens in their web UI, which I don't like because it makes it hard to know what we've changed.
This automates the custom ranking that makes use of the new attribute
coreadded in the first commit.I also moved all of the algolia scripts to a directory to keep them together since that collection keeps growing.