search

akka / akka-http

The Streaming-first HTTP server/module of Akka
https://doc.akka.io/libraries/akka-http/current/
Other
1.34k stars 594 forks source link

Make sure that all documentation pages / sections are available both for Java and Scala (or provide stubs) #1711

Open jlprat opened 6 years ago

jlprat commented 6 years ago

The new Doc pages will be in the same page from now on, this means the URL is the same for Scala and Java API/DSL. We need to make sure Algolia can index both contents (Algolia searches also text within the page) and that the links in the result section link to the current selected language.

To determine the language

Currently the Algolia snippet checks for language by looking at window.location.pathname and checking if such path includes /java/ or java.html. Otherwise it determines it's Scala.

For the new docs, we should search on window.location.search for example, and check if such query parameter contains language=java, otherwise Scala.

raboof commented 6 years ago

Perhaps algolia doesn't need to be aware of the language at all anymore? (https://github.com/akka/akka-paradox/pull/23)

Indeed it might be good to double-check Algolia also indexes the text that is specific to one of the languages, but I'm not sure it is worth it to switch languages based on the search result.

Perhaps relatedly, it appears algolia currently indexes all versions (and thus produces 'duplicate' result). Should we add a version facet to our query or update algolia so that they only index current?

jlprat commented 6 years ago

There is only the case where a section is on only 1 language (the one not indexed) and then you'll never be able to find it in search. For example, I can imagine somebody searching for Jackson and having trouble finding it because Algolia indexes only the Scala part

raboof commented 6 years ago

Right, I agree we should make sure both Java-specific and Scala-specific content is indexed.

I think it might be acceptable when searching for 'jackson' would point to https://doc.akka.io/docs/akka-http/current/common/json-support.html#jackson-support - even though this is kind of puzzling when you have selected 'Scala' as the language, since that section is not visible for Scala. (actually, you could argue we might want to introduce a small note for Scala users there?)

jlprat commented 6 years ago

Adding the note for features only present on the other API, sounds like a quick win, but I don't know by heart how many of such sections there are.

ktoso commented 6 years ago

Not that many I think, definitely doable

ktoso commented 6 years ago

The algolia PR was merged, anything to follow up here? Need to release akka-paradox etc ofc.

jlprat commented 6 years ago

mmm... I guess we could have this ticket to find sections that are only in one language and surface them in the other language stating that is only available in xxxxxDSL