Improve the targets in doc/Makefile

[core-man]

Description of proposed changes

• help target
  • List information of clean, api, and serve
  • Tiny improvement for the html information
• Change the order of all the targets
  • the original order: all, help, clean, html, api, linkcheck, doctest, serve
  • the new order: help, all, html, api, serve, linkcheck, dotest, clean.
• Tiny improvment of the clean target

The following are some of my thoughts on which I want your comments:
- [ ] Now the all target is the same as the html, so shall we remove the all target?

• We have added a workflow to check links in plaintext and HTML files in Add a workflow checking links in plaintext and HTML files #634, so do we want to remove the linkcheck target (originally posted in Add more targets to doc/makefile help information #914 (comment))?
• There are modules and ipynb_checkpoints in the clean target, but I cannot find them after I made all the targets. So remove them?
• Shall we rename the serve target to be server?

Fixes #914

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[seisman]

• Change the order of all the targets

  • the original order: all, help, clean, html, api, linkcheck, doctest, serve
  • the new order: help, all, html, api, serve, linkcheck, dotest, clean.

Putting help in the first place makes more sense to me. In the old Makefile, running make builds the documentation. Now running make shows the help message.

The following are some of my thoughts on which I want your comments:

• Now the all target is the same as the html, so shall we remove the all target?

I still want to keep the all target, because it's commonly used in almost all Makefiles.

• We have added a workflow to check links in plaintext and HTML files in Add a workflow checking links in plaintext and HTML files #634, so do we want to remove the linkcheck target (originally posted in #914 (comment))?

@weiji14 is removing both linkcheck and doctest targets in PR #991. I think it makes more sense to remove it in this PR. @weiji14 thoughts?

• There are modules and ipynb_checkpoints in the clean target, but I cannot find them after I made all the targets. So remove them?

Sounds OK to me.

• Shall we rename the serve target to be server?

I have seen both in other projects. So I'm OK with either.

[weiji14]

• We have added a workflow to check links in plaintext and HTML files in Add a workflow checking links in plaintext and HTML files #634, so do we want to remove the linkcheck target (originally posted in #914 (comment))?

@weiji14 is removing both linkcheck and doctest targets in PR #991. I think it makes more sense to remove it in this PR. @weiji14 thoughts?

Yes please do it here instead, feel free to cherry-pick commit 89f1f94 and f04173b.

[core-man]

• We have added a workflow to check links in plaintext and HTML files in Add a workflow checking links in plaintext and HTML files #634, so do we want to remove the linkcheck target (originally posted in #914 (comment))?

@weiji14 is removing both linkcheck and doctest targets in PR #991. I think it makes more sense to remove it in this PR. @weiji14 thoughts?

Yes please do it here instead, feel free to cherry-pick commit 89f1f94 and f04173b.

hmm~ I even did not know cherry-pick. Now I understand why we need to submit each small revision in one commit.
Done in 290bb2a and 5cf3674.

[core-man]

• There are modules and ipynb_checkpoints in the clean target, but I cannot find them after I made all the targets. So remove them?

Sounds OK to me.

Done in 61ff7b7.

• Shall we rename the serve target to be server?

I have seen both in other projects. So I'm OK with either.

Done in 4733351.

[weiji14]

Looking good, just one more suggestion on alphabetically ordering the Makefile targets.

Also, could you change the title of this PR to be a bit more descriptive? E.g. "Improve help section of Makefile" or something like that. It's generally a good idea to be more specific on what are the main changes that were made so that people scanning the git log know what happened.

[weiji14]

Maybe sort these lines alphabetically?

Suggested change

	@echo " html build the HTML files from the existing rst sources"
	@echo " api generate rst source files of API documentation"
	@echo " server make a local HTTP server for previewing the built documentation"
	@echo " clean clean up built and generated files"
	@echo " api generate rst source files of API documentation"
	@echo " clean clean up built and generated files"
	@echo " html build the HTML files from the existing rst sources"
	@echo " server make a local HTTP server for previewing the built documentation"

I'd also prefer it if the rest of this Makefile was sorted alphabetically (i.e. all, api, clean, html, server), while keeping this help target on top of course.

[core-man]

People usually put clean to be the last one, while the target like all or install/build/html is the first one in a makefile. Shall we keep this rule? @seisman @willschlitzer How do you think?

[seisman]

I prefer to put clean at the bottom.

[core-man]

@weiji14 @seisman Change the order to be all, api, html, server, and clean in e719f74. So keep all first, clean last, and sort the other alphabetically.

[core-man]

Also, could you change the title of this PR to be a bit more descriptive? E.g. "Improve help section of Makefile" or something like that. It's generally a good idea to be more specific on what are the main changes that were made so that people scanning the git log know what happened.

Great~ I once thought to always have a title that can represent all the changes in one PR:joy:. Change to be "Improve the help target of doc/Makefile"

[seisman]

Looks good to me, but ping @weiji14 @meghanrjones @willschlitzer for comments.

[seisman]

@core-man Please update the PR description based on the changes in this PR.

[maxrjones]

Nice!