pulsar icon indicating copy to clipboard operation
pulsar copied to clipboard
verified publisher icon apache

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

Open momo-jun opened this issue 3 years ago • 10 comments

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

  • [x] doc

momo-jun avatar Aug 03 '22 08:08 momo-jun

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

momo-jun avatar Aug 05 '22 02:08 momo-jun

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

momo-jun avatar Aug 05 '22 04:08 momo-jun

  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/...).

Anonymitaet avatar Aug 08 '22 01:08 Anonymitaet

@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.

  1. 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.

momo-jun avatar Aug 08 '22 02:08 momo-jun

@momo-jun pls resolve the conflicts

urfreespace avatar Aug 08 '22 03:08 urfreespace

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 image

Anonymitaet avatar Aug 08 '22 05:08 Anonymitaet

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.

momo-jun avatar Aug 09 '22 07:08 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.

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

urfreespace avatar Aug 10 '22 01:08 urfreespace

@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.

momo-jun avatar Aug 10 '22 01:08 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.

Do you mean the red is determined by the green?

image

Anonymitaet avatar Aug 10 '22 03:08 Anonymitaet

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

momo-jun avatar Aug 10 '22 13:08 momo-jun

@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

urfreespace avatar Aug 11 '22 06:08 urfreespace