[docs] Rework API docs

[chalin]

• Contributes to
  • Non-API docs should be hosted on the website only #2172
  • Migrate Python docs to this repo opentelemetry.io#1109
• Index page sections and other pages are moving to the OTel website via opentelemetry.io PR#1116. This PR removes the sections & pages that have migrated, and reworks the index page a bit. Here the parts that are being moved:
  • https://opentelemetry-python.readthedocs.io/en/stable/getting-started.html → https://opentelemetry.io/docs/instrumentation/python/getting-started/
  • https://opentelemetry-python.readthedocs.io/en/stable/faq-and-cookbook.html → https://opentelemetry.io/docs/instrumentation/python/cookbook/
  • https://opentelemetry-python.readthedocs.io/en/stable/performance/benchmarks.html → https://opentelemetry.io/docs/instrumentation/python/#learn-more
• I've also added index pages for some of the sections to make it easier to reference (and it makes breadcrumbs work better for those sections).

/cc @cartermp @austinlparker

Preview: ... hmm, I'm not sure how to link to a preview -- anyone else know? In the meantime, I've included a screenshot below.

---

[chalin]

It might be desirable to implement Redirects for pages that have been renamed or removed, but apparently it requires access to the readthedocs.org account, which I don't have access to. Let me know if you think this is worth exploring further, and who might be available to help set it up.

[lzchen]

Is there a place we can put the excerpt related to benchmarks?

Click here https://open-telemetry.github.io/opentelemetry-python/benchmarks/index.html_ to view the latest performance benchmarks for packages in this repo.

[chalin]

Is there a place we can put the excerpt related to benchmarks?

@izchen, the intent of

• Non-API docs should be hosted on the website only #2172

is to avoid non-API info in the API reference pages. The link to benchmarks is available from the Python landing page (or will be once open-telemetry/opentelemetry.io#1116 is merged).

[lzchen]

@chalin
Should a benchmarks.md exist here then?

[chalin]

@chalin Should a benchmarks.md exist here then?

I does (in a sense I explain next), I just merged the PR (open-telemetry/opentelemetry.io#1116) that adds the link to the benchmarks to that page.

Note that I didn't add the content of benchmarks.md because that page just told user to "click 'here'". Instead I added the direct link:

[chalin]

Thanks for the thumbs up on my last comment @lzchen.

All: are there any points left to address before this gets approved and merged? Thanks.

[chalin]

I noticed that other doc changes had a CHANGELOG entry, so I added one. PTAL.

[chalin]

I've also updated the opening comment to explicitly list the pages that have moved along with what they redirect to.

[chalin]

Followup to last week's ping: is there anything left to do before this can get merged?

[lzchen]

@ocelotl
Have your comments been addressed?

[chalin]

Thanks all for your approvals. Can this be merged now?