[feature][doc]PIP-190: Generate 2.10.x/2.9.x/2.8.x docs

[momo-jun]

Motivation

Refer to PIP-190.

Modifications

1. Rename version-2.8.0/2.9.0/2.10.0 to version-2.8.x/2.9.x/2.10.x
2. Add 2.8.1/2.8.2/2.8.3 specific doc changes to 2.8.x docs.
3. Add 2.9.1/2.9.2/2.9.3 specific doc changes to 2.9.x docs.
4. Add 2.10.1 specific doc changes to 2.10.x docs.
5. Refresh the versions.json file.
6. Add .md to fix 200+ broken links in 2.8.x/2.9.x docs

Documentation

• doc

[momo-jun]

Ping @Anonymitaet @urfreespace for review.
This PR needs to work with #16938.

[momo-jun]

@BewareMyPower FYI - with this change implemented, you don't need to generate docs for the upcoming 2.8.4 release.

[Anonymitaet]

1. How about not deleting 2.8.1/2.8.2/2.8.3/2.9.1/2.9.2/2.9.3/2.10.1 docs since there might be some occurrences referencing them? We can just not show them.

2. How about adding some explanations for this PR change on https://pulsar.apache.org/versions? So that users will not be confused by the different version formats (2.10.x/2.9.x/2.8.x and 2.7.4/2.7.3/2.7.2/2.7.1/...).

[momo-jun]

@Anonymitaet Thanks for your suggestions.

1. How about not deleting 2.8.1/2.8.2/2.8.3/2.9.1/2.9.2/2.9.3/2.10.1 docs since there might be some occurrences referencing them? We can just not show them.

Keeping these obsolete docs may confuse contributors and lead to errors when they update them.
On the other hand, I searched in the versioned docs and there were no cross-version links found. If we do have such occurrences, we should fix them.

2. How about adding some explanations for this PR change on https://pulsar.apache.org/versions? So that users will not be confused by the different version formats (2.10.x/2.9.x/2.8.x and 2.7.4/2.7.3/2.7.2/2.7.1/...).

I will try to add some explanations there.

[urfreespace]

@momo-jun pls resolve the conflicts

[Anonymitaet]

How about not deleting 2.8.1/2.8.2/2.8.3/2.9.1/2.9.2/2.9.3/2.10.1 docs since there might be some occurrences referencing them? We can just not show them.
Keeping these obsolete docs may confuse contributors and lead to errors when they update them.
On the other hand, I searched in the versioned docs and there were no cross-version links found. If we do have such occurrences, we should fix them.

1. I mean the outside occurrences. We try not to delete doc sets as much as possible since it might cause some errors elsewhere we do not know.

2. Can we inform users on how to update docs as below?

Take not to update 2.8.1 - 2.8.4 as an example

2.1 Add notes and instructions to the Pulsar documentation contribution guide

2.2 Add deprecate to folder names, in this way, users get the info quickly

[momo-jun]

Hi @urfreespace, as @Anonymitaet suggested, if we add deprecated to the folders as a comprise to balance the confusion elimination and the potential external link issue, do you see any risk here? If it's good to go, I will rename these folders in this PR as well.

[urfreespace]

Hi @urfreespace, as @Anonymitaet suggested, if we add deprecated to the folders as a comprise to balance the confusion elimination and the potential external link issue, do you see any risk here? If it's good to go, I will rename these folders in this PR as well.

I think it's a good idea, but I suggest we should make another PR to do that after we merged this PR and make sure it's working well

[momo-jun]

@Anonymitaet adding deprecated to those folders will change the URLs of doc pages, which also breaks the external references. If that's the case, I think I will also have to close the PR and open another one to avoid renaming the current 2.10.0/2.9.0/2.8.0 doc sets.

[Anonymitaet]

@Anonymitaet adding deprecated to those folders will change the URLs of doc pages, which also breaks the external references. If that's the case, I think I will also have to close the PR and open another one to avoid renaming the current 2.10.0/2.9.0/2.8.0 doc sets.

Do you mean the red is determined by the green?

[momo-jun]

@Anonymitaet Yes, I talked with @urfreespace about the renaming today.
@urfreespace Can you pls help confirm it to avoid any misunderstanding here?

[urfreespace]

@Anonymitaet Yes, I talked with @urfreespace about the renaming today. @urfreespace Can you pls help confirm it to avoid any misunderstanding here?

yes, we should consider creating another PR for the work of renaming after the current PR merged and make sure it's working well