DocSearch comparison - Githubissues

open-contracting / ocds-index

A command-line tool and library to index OCDS documentation in Elasticsearch

https://ocds-index.readthedocs.io

BSD 3-Clause "New" or "Revised" License

0 stars 0 forks source link

DocSearch comparison #7

Open jpmckinney opened 3 years ago

jpmckinney commented 3 years ago

https://docsearch.algolia.com is used by https://framework.frictionlessdata.io/docs/guides/guides-overview among others. (They also use https://docusaurus.io)

It looks like it supports multilingual websites: https://docsearch.algolia.com/docs/config-file/#using-regular-expressions

To ignore navigation, footers, etc. use selectors_exclude: https://docsearch.algolia.com/docs/config-file/#selectors_exclude-optional

We'd like to add results from the Extension Explorer #2. start_urls might be the way for DocSearch to do that: https://docsearch.algolia.com/docs/config-file/#start_urls

Since we already have a working setup that is timely (DocSearch runs daily) and configurable, I'm just noting the option here, in case we run into major development work around OCDS Index or Elasticserach, at which point we can reconsider.

jpmckinney commented 3 years ago

Can follow Executable Books' use here: https://github.com/executablebooks/jupyter-book/issues/1324

jpmckinney commented 3 years ago

Unique features of DocSearch are auto-completion and instant-search.

I'll re-open, as adopting DocSearch could:

Reduce the time to close #2 (which requires not just indexing, but also integrating the results meaningfully)
Eliminate the cost of maintaining and updating our Elasticsearch instance
Eliminate the cost of re-integrating our custom search into the new theme https://github.com/open-contracting/standard/pull/1254#issuecomment-822971743

I'm not sure DocSearch will work for staging documentation (re: start_urls). We can fallback to Sphinx's default search in that case.

jpmckinney commented 3 years ago

If we move to ReadTheDocs https://github.com/open-contracting/deploy/issues/266, we might instead use its existing search features, which already searches across subprojects: https://docs.readthedocs.io/en/stable/guides/searching-with-readthedocs.html

jpmckinney commented 3 years ago

Re-opening pending conclusion of https://github.com/open-contracting/deploy/issues/266

jpmckinney commented 3 years ago

Some instructions for Sphinx integration: https://github.com/readthedocs/sphinx_rtd_theme/issues/761