Reorganization of the Sphinx docs to only include reference pages

[miguelgrinberg]

Reorganization of the Sphinx docs to only include reference pages.

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[pquentin]

LGTM, but we should wait for HTTP redirects to be in place before merging IMO.

Including a redirect from /api.html to /index.html.

[miguelgrinberg]

@pquentin Redirect table proposal:

source	8.18	9.0+
/en/latest/	No change	No change
/en/latest/quickstart.html	https://www.elastic.co/guide/en/elasticsearch/client/python-api/8.18/getting-started-python.html	https://www.elastic.co/docs/reference/elasticsearch-py/getting-started
/en/latest/interactive.html	https://www.elastic.co/guide/en/elasticsearch/client/python-api/8.18/examples.html	https://www.elastic.co/docs/reference/elasticsearch-py/examples
/en/latest/api.html	/en/latest/index.html	/en/latest/index.html
/en/latest/exceptions.html	No change	No change
/en/latest/async.html	https://www.elastic.co/guide/en/elasticsearch/client/python-api/8.18/async.html	https://www.elastic.co/docs/reference/elasticsearch-py/async
/en/latest/helpers.html	https://www.elastic.co/guide/en/elasticsearch/client/python-api/8.18/client-helpers.html	https://www.elastic.co/docs/reference/elasticsearch-py/client-helpers

The api.html, async.html and helpers.html exist in both old and new designs. Would it make sense rename these pages in the redesigned docs, so that we can add the redirects above and also have pages we can link from now on?

And aside from this, it is unfortunate but I think we are going to have to create redirects for each version that we publish, until we decide this isn't necessary anymore, because we want the <= 8.17 docs to be redirect free, meaning that we cannot do generic redirects across all versions.

[pquentin]

The api.html, async.html and helpers.html exist in both old and new designs. Would it make sense rename these pages in the redesigned docs, so that we can add the redirects above and also have pages we can link from now on?

Yes, good point.

And aside from this, it is unfortunate but I think we are going to have to create redirects for each version that we publish, until we decide this isn't necessary anymore, because we want the <= 8.17 docs to be redirect free, meaning that we cannot do generic redirects across all versions.

That makes sense. The free plan we're using allows for 100 redirects, but I'm assuming we will only need redirects for latest, stable, 8.18, 8.19, 9.0 and 9.1, not much more than that?

[miguelgrinberg]

All pages renamed so that there are no collisions with the redirects. I guess we can wait until the new docs system is in place to see if the redirects above need to be adjusted, and only merge this PR after we put those in.

[miguelgrinberg]

Rebased to incorporate minor changes made during the docs migration to markdown.

[pquentin]

Why was this renamed? This is going to break existing links, I believe

[miguelgrinberg]

This is to avoid collisions when we add the redirects. Look at the table above. Requests to /en/latest/api.html will be redirected to /en/latest/index.html, since now the whole site is reference documentation. This page is renamed because if not there would be no way to create a direct link to it, given that it collides with the redirect.

Side note, the URLs under the new doc system are different, so the second column of the redirect table above needs to be updated to match the markdown doc URLs (and hopefully the docs team have added their own redirects from the old URLs to the new.)

[pquentin]

Should we link to the main docs?

[miguelgrinberg]

Yes, we should add links to the guide in all the reference pages where there is a reasonable page to link to. I'm looking into this.

[miguelgrinberg]

@pquentin I have updated the redirect table. It now has redirects for 8.18 and 9.0+ separately. I need to confirm that I've got the 9.0 links right, since these are not deployed yet and I'm building them based on previews and descriptions of what the URL system is going to be.

Can you confirm that this looks good?
There was an outstanding question you had regarding the rename of api.html to es-api.html. Do you now understand why I did this, or do we need to discuss this more?

[pquentin]

Sounds good! We can set up the 9.0 redirects when the docs are live. Yes, es-api.html, makes sense.

Thank you for this work