[docs] Add docs for topic rate limiting

[gmethvin]

Motivation

It's not completely clear from the documentation that you can set dispatch rates for individual topics in pulsar-admin.

Modifications

I've added docs for that and also made some wording changes to the other rate limiting sections to make them more clear.

[Anonymitaet]

@gmethvin many thanks for your contribution.

However, reference-pulsar-admin.md has been deprecated from the sidebar since the contents on that page always lag behind the code (and the manual maintenance cost is high). Users can get the latest info here: http://pulsar.apache.org/tools/pulsar-admin/2.9.0-SNAPSHOT/#-em-get-dispatch-rate-em--69

For pulsar-admin doc, docs can be added (as descriptions) w/ code in the code file: https://github.com/apache/pulsar/tree/master/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cl. After the PR is merged, the doc will be automatically generated from the code file and the doc will be shown on the page (http://pulsar.apache.org/tools/pulsar-admin/2.9.0-SNAPSHOT/#-em-get-dispatch-rate-em--69)

So could you please revert changes in these md files and add explanations in the code files? thanks

[gmethvin]

@Anonymitaet Thanks for pointing me to the code and the other documentation page. I think we still have a problem, though, as there is no indication on https://pulsar.apache.org/docs/en/pulsar-admin/ that the page is deprecated, yet it is the page most people are likely to land on when looking for pulsar-admin documentation. It appears prominently in Google search results, and the main documentation page (https://pulsar.apache.org/docs/en/standalone/) also still links to that page. I think we should display a deprecation message linking to the new page, or perhaps even add a redirect to the new page.

Also, is there a similar code file for https://github.com/apache/pulsar/blob/master/site2/docs/admin-api-topics.md? I noticed that didn't have information on topic dispatch rate limiting either.

[Anonymitaet]

Hi @gmethvin thanks for your suggestions.

I've submitted a PR (#11146) to fix the issues you mentioned as below, could you please help review the PR? Many thanks

1. On this page (https://pulsar.apache.org/docs/en/pulsar-admin/), I've added some explanations about this page is deprecated and the info about how users can get the latest and complete info.

2. Replace https://pulsar.apache.org/docs/en/pulsar-admin/ with http://pulsar.apache.org/tools/pulsar-admin/ in multiple docs to direct users to the correct place.

3. Admin API chapters (https://pulsar.apache.org/docs/en/next/admin-api-overview/) are in the same situation, I've added the explanations and direct users to the correct place.
   Adding contents to Admin API chapters manually is time-consuming and error-prone. Moreover, it is not easy and changeling for writers to catch up all code changes and sync them with docs. If the Admin API pages can be generated from code automatically, that would be more efficient.

4. Besides, I've updated some contents and fixed some wrong links.

P.S. for your PR, it would be much appreciated if you can add explanations in the code files correspondingly.

[gmethvin]

Closing this PR since it seems like the existing documentation from the code has the most important fixes I've added here. When I get a chance I can review the other pulsar-admin and REST API pages in more detail to clarify the wording.