Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove the "documentation for other versions" section from the README file #1358

Closed
Tracked by #1402
seisman opened this issue Jun 24, 2021 · 12 comments · Fixed by #1415
Closed
Tracked by #1402

Remove the "documentation for other versions" section from the README file #1358

seisman opened this issue Jun 24, 2021 · 12 comments · Fixed by #1415
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Milestone

Comments

@seisman
Copy link
Member

seisman commented Jun 24, 2021

The "documentation for other versions" section in the README file is becoming longer as we release more versions:

image

Since we already have a version switcher on the main site, and the version switcher is easy to use, I think we can remove the "documentation for other versions" section from the README file.

image

@seisman seisman added question Further information is requested documentation Improvements or additions to documentation labels Jun 24, 2021
@core-man
Copy link
Member

Sound good.

  • PyGMT users could find documentation of different versions using the version switcher on the main site.
  • PyGMT contributors/maintainers could find the version records at /doc/_static/version_switch.js

@seisman
Copy link
Member Author

seisman commented Jun 25, 2021

I'll mark it as "good first issue" and "first-timer-only" if @GenericMappingTools/pygmt-maintainers have no objections.

@weiji14
Copy link
Member

weiji14 commented Jun 25, 2021

Alternatively, we could link to the old version docs page at the Compatibility with GMT/Python/NumPy versions table? I feel like keeping a proper link somewhere is good, since the Javascript dropdown isn't very accessible, and can't be used in some places like the PyPI page.

@seisman
Copy link
Member Author

seisman commented Jun 25, 2021

Alternatively, we could link to the old version docs page at the Compatibility with GMT/Python/NumPy versions table? I feel like keeping a proper link somewhere is good, since the Javascript dropdown isn't very accessible, and can't be used in some places like the PyPI page.

I just recalled your accessibility concern at #621 (comment).

just pointing out that the dropdown isn't super-accessible. I managed to tab-tab-tab my way to the version changer dropdown (with the benefit of sight), and change to a different version of the documentation by pressing up/down with my arrow keys (only once though, it doesn't seem to allow scrolling through the list of options).

Could you explain more about the dropdown accessibility? What do you expect?

@weiji14
Copy link
Member

weiji14 commented Jun 25, 2021

Could you explain more about the dropdown accessibility? What do you expect?

Thanks for digging up that comment :) I expect that someone using only their keyboard can access other versions of PyGMT's documentation.

@seisman
Copy link
Member Author

seisman commented Jun 26, 2021

I expect that someone using only their keyboard can access other versions of PyGMT's documentation.

I think it already works, no? I can use Tab to navigate the PyGMT site and also use up-down keys to select specific versions.

@weiji14
Copy link
Member

weiji14 commented Jun 26, 2021

I expect that someone using only their keyboard can access other versions of PyGMT's documentation.

I think it already works, no? I can use Tab to navigate the PyGMT site and also use up-down keys to select specific versions.

Maybe it work on your browser? On Firefox for me (edit: same issue on Brave browser), I can only use Tab to select one version above or below the current one as mentioned in #621 (comment). If I'm at v0.3.1, it jumps directly to v0.4.0 or v0.3.0 if I press the up or down button (this is before I press Enter). So if I want to go to v0.1.2, I need to tab to the version switcher, press down, let the page reload to the new version, and repeat 4 times to go from v0.4.0 -> v0.3.1 -> v0.3.0 -> v0.2.1 -> v0.1.2.

@seisman
Copy link
Member Author

seisman commented Jun 29, 2021

It works well for me on Microsoft Edge, Safari, but not on Firefox.

@weiji14
Copy link
Member

weiji14 commented Jun 30, 2021

Ok, if we do want to remove it, maybe we could put the old links at the Compatibility table as I mentioned in #1358 (comment), so that it looks like this:

image

i.e. have every minor version point to the latest patch release, e.g. v0.4.x points to v0.4.0, v0.3.x points to v0.3.1 and so on

@@ -234,12 +234,12 @@ Documentation for other versions
 Compatibility with GMT and Python/NumPy versions
 ------------------------------------------------
 
-======= ========== ========= =========
-PyGMT   GMT        Python    NumPy
-======= ========== ========= =========
-0.4.x   >=6.2.0    >=3.7     >=1.17.0
-0.3.x   >=6.1.1    >=3.7
-0.2.1   >=6.1.1    >=3.6
-0.2.0   >=6.1.1    3.6 - 3.8
-0.1.x   >=6.0.0    3.6 - 3.8
-======= ========== ========= =========
+========================================== ========== ========= =========
+PyGMT                                      GMT        Python    NumPy
+========================================== ========== ========= =========
+`v0.4.x <https://www.pygmt.org/v0.4.0>`__  >=6.2.0    >=3.7     >=1.17.0
+`v0.3.x <https://www.pygmt.org/v0.3.1>`__  >=6.1.1    >=3.7
+`v0.2.1 <https://www.pygmt.org/v0.2.1>`__  >=6.1.1    >=3.6
+`v0.2.0 <https://www.pygmt.org/v0.2.0>`__  >=6.1.1    3.6 - 3.8
+`v0.1.x <https://www.pygmt.org/v0.1.2>`__  >=6.0.0    3.6 - 3.8
+========================================== ========== ========= =========

@core-man
Copy link
Member

core-man commented Jun 30, 2021

On Firefox for me (edit: same issue on Brave browser), I can only use Tab to select one version above or below the current one as mentioned in #621 (comment). If I'm at v0.3.1, it jumps directly to v0.4.0 or v0.3.0 if I press the up or down button (this is before I press Enter). So if I want to go to v0.1.2, I need to tab to the version switcher, press down, let the page reload to the new version, and repeat 4 times to go from v0.4.0 -> v0.3.1 -> v0.3.0 -> v0.2.1 -> v0.1.2.

Same with me. I use Google Chrome and Firefox on CentOS7.5.

Ok, if we do want to remove it, maybe we could put the old links at the Compatibility table as I mentioned in #1358 (comment), so that it looks like this:

Sounds good.

@willschlitzer
Copy link
Contributor

Ok, if we do want to remove it, maybe we could put the old links at the Compatibility table as I mentioned in #1358 (comment), so that it looks like this:

I think this looks much cleaner than the old version; I'm a fan!

@seisman
Copy link
Member Author

seisman commented Jul 28, 2021

Ok, if we do want to remove it, maybe we could put the old links at the Compatibility table as I mentioned in #1358 (comment), so that it looks like this:

image

i.e. have every minor version point to the latest patch release, e.g. v0.4.x points to v0.4.0, v0.3.x points to v0.3.1 and so on

@@ -234,12 +234,12 @@ Documentation for other versions
 Compatibility with GMT and Python/NumPy versions
 ------------------------------------------------
 
-======= ========== ========= =========
-PyGMT   GMT        Python    NumPy
-======= ========== ========= =========
-0.4.x   >=6.2.0    >=3.7     >=1.17.0
-0.3.x   >=6.1.1    >=3.7
-0.2.1   >=6.1.1    >=3.6
-0.2.0   >=6.1.1    3.6 - 3.8
-0.1.x   >=6.0.0    3.6 - 3.8
-======= ========== ========= =========
+========================================== ========== ========= =========
+PyGMT                                      GMT        Python    NumPy
+========================================== ========== ========= =========
+`v0.4.x <https://www.pygmt.org/v0.4.0>`__  >=6.2.0    >=3.7     >=1.17.0
+`v0.3.x <https://www.pygmt.org/v0.3.1>`__  >=6.1.1    >=3.7
+`v0.2.1 <https://www.pygmt.org/v0.2.1>`__  >=6.1.1    >=3.6
+`v0.2.0 <https://www.pygmt.org/v0.2.0>`__  >=6.1.1    3.6 - 3.8
+`v0.1.x <https://www.pygmt.org/v0.1.2>`__  >=6.0.0    3.6 - 3.8
+========================================== ========== ========= =========

I think we are OK with this solution. I have marked it as "good first issue" and add it to the v0.4.1 milestone.

@seisman seisman added this to the 0.4.1 milestone Jul 28, 2021
@seisman seisman added good first issue Good for newcomers and removed question Further information is requested labels Jul 28, 2021
@core-man core-man mentioned this issue Jul 31, 2021
23 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants