feat: customize search_data for an extra
#2017
Conversation
|
📦 Docs artifacts are ready: https://github.com/elixir-lang/ex_doc/actions/runs/12757638151/artifacts/2425291365 |
|
To get an idea of how it works, see this test: |
| {"test/fixtures/README.md", | ||
| search_data: [ | ||
| %{ | ||
| anchor: "heading-without-content", |
There was a problem hiding this comment.
There is one particular annoyance here. The top item of the search data is the "module body" of the page, and it doesn't have an anchor. So we need to allow anchor to be an empty string and add a test that we emit the proper code (i.e. no trailing #).
zachdaniel
force-pushed
the
customize-extra-search-data
branch
from
11fbc6e to
ba72416
Compare
|
@josevalim I believe I've addressed your comments. Instead of using Also added a test in the js spec. |
zachdaniel
force-pushed
the
customize-extra-search-data
branch
from
ba72416 to
c367a89
Compare
zachdaniel
force-pushed
the
customize-extra-search-data
branch
from
c367a89 to
e84b754
Compare
zachdaniel
force-pushed
the
customize-extra-search-data
branch
from
e84b754 to
b1ee88b
Compare
|
Okay @josevalim I think it should align better with what you are looking for now (which is better than what I had). There is still some conditional logic changes required in the autocomplete code, but I've explained each in a comment. |
|
@josevalim ready for another round 🙇 |
|
@josevalim done. |
|
lemme squash all these commits actually. Okay, now its good to go. |
This allows configuring the "search data" for any given extra. When you do this, you take over the way that the extra appears both in autocomplete and in search_data. The current system assumes that you give this information in markdown, which I think is a safe assumption, but we could do something like allow for an html_body or markdown_body to be given, etc. This is likely not going to be useful for 99% of people, and as such I think its okay that its not super ergonomic. Specifically, you have to completely manage the search content etc. The way this will be used, however, is in Spark where we generate markdown files for DSL documentation. With this change, we can add a function called Spark.Dsl.search_data_for(Your.Dsl) which will improve the autocomplete experience and the search experience in various ways (by adding more things to autocomplete than just headers, and by customizing the type of the search data nodes
zachdaniel
force-pushed
the
customize-extra-search-data
branch
from
10cbe36 to
effbc74
Compare
|
@josevalim done |
|
💚 💙 💜 💛 ❤️ |
This allows configuring the "search data" for any given extra. When you do this, you take over the way that the extra appears both in autocomplete and in search_data. The current system assumes that you give this information in markdown, which I think is a safe assumption, but we could do something like allow for an
html_bodyormarkdown_bodyto be given, etc.This is likely not going to be useful for 99% of people, and as such I think its okay that its not super ergonomic. Specifically, you have to completely manage the search content etc. The way this will be used, however, is in
Sparkwhere we generate markdown files for DSL documentation. With this change, we can add a function calledSpark.Dsl.search_data_for(Your.Dsl)which will improve the autocomplete experience and the search experience in various ways (by adding more things to autocomplete than just headers, and by customizing thetypeof the search data nodes@josevalim I know we had discussed a sort of "unification" of search-data and sidebar-items, but I think this does let me kick the can down the road a little bit.
With this PR
ex_docprovides a way to customize the search data for extras (which I need) that encompasses all of the information that currently drives both search-data and sidebar-items. This means that we are free to refactor those two files internally, and my code that customizes searchable content for extras won't be affected. Additionally, since you configure thesearch_datafor an extra completely (it replaces the autogenerated search data), we don't double index the same material but differently.If this approach is amenable then I can work up some documentation and add some additional tests for how it modifies search data. Only didn't do that because I think there will be some discussion/back and forth on naming, implementation, etc. (or even if this is something that ex_doc will accept 😄 )