Clarify description of "Sphinx" in alternatives

[jbms]

It would be nice if in the alternatives section you mentioned that Sphinx Immaterial contains a modified search implementation that provides similar functionality to mkdocs-material.

Currently it lists "Search is less powerful than the one provided by MkDocs" which may be true for the normal search functionality in Sphinx (you have to press enter and go to a new page to see results rather than seeing them in a dropdown as you type, search is not aware of document sections and always just links to the top of the page except for "objects").

However, the heavily modified version of Sphinx search in sphinx immaterial provides similar functionality to mkdocs-material and actually has some advantages:

• search results are displayed in exactly the same way, updated as you type
• search is section-aware, and search results link to the actual document section
• snippets are chosen to include search terms
• search index may be more compact because it only includes terms, not the full text of every page.

[squidfunk]

Thanks for suggesting. Albeit I understand your concern, I'm not planning to advertise features of specific alternatives or themes. You're not advertising Material for MkDocs as an alternative on the documentation of Sphinx Immaterial either or contributing anything back, you're only profiting off years of my work. This guide is meant for users to be able to explore alternatives before deciding to settle. If you want, I can remove the reference to Sphinx Immaterial altogether, as it doesn't help this project.

[jbms]

Hi Martin,

I would definitely like to avoid any conflict, and I would certainly hope that what we've done with sphinx immaterial does not offend you. I can certainly understand that you may not wish to elaborate on alternatives and that is fine, and of course it is your decision whether to remove the reference to sphinx immaterial altogether.

The Sphinx immaterial documentation clearly indicates that it is an adaptation of your theme to sphinx, which I think therefore makes clear that users looking for a similar theme for mkdocs should obviously just use your theme. However if you would prefer some other way of mentioning your theme we're open to suggestions.

It is true that I am profiting off of your work, but only in that I am able to use it, just like any other user. We aren't soliciting donations for sphinx immaterial. I have contributed the occasional bug report and pull request, but I have not provided any financial support.

In fact I don't think of sphinx-immaterial as a competing theme, since it is 95%+ the same theme. So you might think of users of that theme as really being users of your theme as well.

I think we might consider adding a note that users who appreciate sphinx immaterial should consider donating to you. In principle someone who sponsors you could manually merge in the insiders changes using the update script, though in practice it might be challenging due to merge conflicts and the need to integrate some of the added features with sphinx. Unfortunately I don't really see a way around that problem.

I actually considered proposing that sphinx support be integrated into your repository rather than having a separate one, but I figured you would not want to maintain that.

[squidfunk]

Thanks for your words. I didn't want to sound harsh. Maybe put yourself in my seat. I'm offering free link juice for your project, saying:

Sphinx Immaterial is a great port of Material for MkDocs to Sphinx, as it follows the upstream repository closely.

Users can visit your site, try the search and see: wow, it feels almost the same! It's actually very positive free advertising for your project. However, what's upsetting you is that the following is said before the link to your project:

Search is less powerful than the one provided by MkDocs

I've tried your search, and I'm still convinced that it is not as powerful as the one provided by MkDocs, let alone default Sphinx search which is not user-friendly. Your search solution suffers from the same problems as all other Sphinx-based solutions: each result has to be fetched separately, which leads to a very poor search experience on slow connections. The search_index.json that is generated by MkDocs can be gzip'd and cached by the browser, so the user has to pay the cost of setting up the search index only once – all interaction with the search is instant, even on slow connections. Furthermore, with the solution you're providing there's no chance to make search work offline, i.e., to distribute your documentation to users for offline usage.

Additionally, please consider that the search solution that is bundled with Insiders is significantly more powerful than the one currently offered on the community version. I invite you to try the search on our official docs. I also invite you to read the blog article explaining why the new search is much better, at least IMHO.

So I leave it up to you. I can either remove the reference to Sphinx Immaterial altogether, as I don't have anything from giving you the free link juice, or we leave it as it is and users find out for themselves. It's just a click away.

[jbms]

Alright, let's leave it as is. I figured that you may not have been aware that sphinx-immaterial used a different search implementation, but you have clarified that you are aware how it works but have still identified some drawbacks, so I can't object to that.

While merging in some of your changes recently I did in fact take a look at your updated search and read your blog post, though I didn't yet take the time to look at the implementation in detail.

When creating sphinx-immaterial I considered the option of just generating an index for use with lunr so that your JavaScript search code could be used unmodified, but I wanted to preserve the special handling in sphinx's search of "objects" (i.e. api documentation entities), and also was concerned about the size of the index and the speed of preprocessing the lunr index in the browser (which your documentation warned about). But I'm not sure if that was the right tradeoff, and perhaps your updated search implementation addresses those issues as well. Note that search is partially supported in sphinx-immaterial when using file:// --- results are found and it is fully functional for objects, but for pages section titles and snippets aren't shown.

The rich search results look nice --- I'll probably try to support that once you've released it from insiders.