[DOCS] Move search API's docvalue_fields examples

[jrodewig]

Changes:

• Condenses and relocates the docvalue_fields example to the 'Search fields'
  section of the 'Run a search' page.
• Adds docs for the docvalue_fields request body parameter.
• Updates several related xrefs.

Relates to #48194

[elasticmachine]

Pinging @elastic/es-docs (>docs)

[elasticmachine]

Pinging @elastic/es-search (:Search/Search)

[jtibshirani]

I overall liked having separate sections for source filtering and docvalue fields, I'm worried it makes it harder to grasp the overall summary if there are detailed reference examples embedded throughout. For comparison, the 'paginate search results' section has outgoing links to 'scroll' and 'search_after'. Perhaps we could add subsections below the top-level summary and move this content there?

[debadair]

I agree with @jtibshirani--I think separate sub sections for source filtering and doc values would make this a bit easier to digest. As it is, it really puts the emphasis on source filtering over doc values.

[jrodewig]

Thanks for the feedback @debadair and @jtibshirani.

I've made some changes based on your feedback, including breaking out separate collapsible sections for source filtering, doc value fields, and stored fields.

You can check out the changes in this preview:
https://elasticsearch_57760.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/run-a-search.html#search-fields

[jtibshirani]

Thanks @jrodewig for the iteration. I took a look at the latest version, and feel like it omits the high-level guidance on how to choose an option. When I added the section #57500, here is the guidance I was trying to convey:

• For retrieving specific fields, source filtering is the right default approach.
• Depending on what limitations you encounter, you may want to try a different approach:
  • docvalue_fields, if the number of fields to retrieve is small and all fields support doc values, otherwise
  • stored_fields as a last expert option

What if we kept the full guidance paragraph, but then had subsections below it for 'source filtering' and 'doc values fields' if the user needs wants detail on each option?

[jrodewig]

Thanks for the feedback @jtibshirani. I incorporated most of your suggestions. One exception is that I left the xref in the existing doc values section of the search request body API docs page.

Because it's an anchor on the page and not a page itself, I can't set up a redirect for it. However, I don't want users that go to that page to wonder where those docs went.

Once we're able to remove the search request body page, I'll be able to set up a redirect and remove that xref.

[jtibshirani]

Looks good to me! I just had one comment about restoring a sentence I was attached to :)

[debadair]

Made a few minor suggestions, but the changes address the main concerns. Thanks!

[jrodewig]

🙇 Thanks so much for your help in getting this over the finish line @debadair and @jtibshirani. I greatly appreciate it.

[jrodewig]

Backport commits

master 7826bbe
7.x d534862
7.8 bfe7850
7.7 cb403a6