-
Notifications
You must be signed in to change notification settings - Fork 348
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
DOC: Combine the modern and classic ReST files into a single file #8486
Comments
I like it. I think we should implemen it. |
While I like the examples in two tabs, I'm afraid I don't like clear the mix of classic and modern in the man pages. I think it is confusing for users. And also, while I'm not really a modern mode user, remember that it was introduced so that new users are advised to use this only. Bring back the classic to front page is a step back on this. |
That's a good point. The problem is, there are still many users who use classic mode and there are also many existing classic-mode scripts. So modern-mode users still need to know at least the existence of the classic mode. I think we just need to have a section explaining the differences between classic and modern modes and then link to that section when necessary. |
For almost all plotting modules, we usually have two separate ReST files for modern and classic modes, respectively. For example, we have
image.rst
andpsimage.rst
andgmtlogo.rst
andgmtlogo-classic.rst
.More ReST files usually mean more maintenance burden, especially sometimes we may fix or update the modern mode examples in one file, but forget to update the corresponding examples in another file.
So, I guess it makes more sense to have only one documentation file for a single module. Usually, the differences of modern and classic ReST files are:
-K
/-O
/-P
is only available in classic modeFor point 1, this can be addressed by emphasizing the these options are classic-mode only. For point 2, modern/classic modes can be switched using sphinx-design's tab directive (https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html).
#8487 is an example PR showing how it works.
The title:
Classic-only options:
Modern-mode example:
Classic-mode examples (after clicking the "Classic mode" Tab:
![Screenshot from 2024-05-13 12-03-10](https://private-user-images.githubusercontent.com/3974108/329919489-5b74683a-d0af-44e4-b663-aa7f4d73b63b.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjM5MjE0MzIsIm5iZiI6MTcyMzkyMTEzMiwicGF0aCI6Ii8zOTc0MTA4LzMyOTkxOTQ4OS01Yjc0NjgzYS1kMGFmLTQ0ZTQtYjY2My1hYTdmNGQ3M2I2M2IucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgxNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MTdUMTg1ODUyWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9M2JlYzliNDYzZWVlMTZkZDE3ZjJiOGJkY2NhZWM3NWFkODViZGFkZTE4MjQ0MTlkMTQ2ODIyOWFmZjZjMzMwOCZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.9mKNOVHh8C_EineQucIC-pIMwJkb4ODB-hGQNUODzTI)
The text was updated successfully, but these errors were encountered: