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

Reorganize tutorial section in the documentation sidebar #1603

Merged
merged 13 commits into from
Nov 14, 2021

Conversation

maxrjones
Copy link
Member

Description of proposed changes

This PR implements the suggestions proposed in #1191 using a folding structure with beginner, intermediate, and advanced sections for the various tutorials.

Here is the appearance with one of the sections expanded:

image

Fixes #1191

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

@weiji14 weiji14 added the documentation Improvements or additions to documentation label Nov 2, 2021
Copy link
Member

@michaelgrund michaelgrund left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. Makes the whole structure much more tidy!

@willschlitzer
Copy link
Contributor

This looks like a good idea (and reminds me that I need to motivate to work on #770 😬 )

@seisman
Copy link
Member

seisman commented Nov 4, 2021

I agree with putting "Gallery", "Projections", "Tutorials" and "External Resources" in the "USER GUIDE" part, but I don't like the subfolder structure for the tutorials. For any new tutorials, we may waste time debating if a tutorial belongs to the "beginner", "intermediate", or "advanced" groups. Personally, I prefer to have all tutorials in the same folder.

@weiji14
Copy link
Member

weiji14 commented Nov 4, 2021

I agree with putting "Gallery", "Projections", "Tutorials" and "External Resources" in the "USER GUIDE" part, but I don't like the subfolder structure for the tutorials. For any new tutorials, we may waste time debating if a tutorial belongs to the "beginner", "intermediate", or "advanced" groups. Personally, I prefer to have all tutorials in the same folder.

Maybe take the middle ground and just have 2 sections (Basics and Advanced as suggested by @core-man in #1191 (comment))? I do think there's a bit of subjectivity on what counts as beginner/intermediate/advanced, so better to make things more simple.

@maxrjones
Copy link
Member Author

I consolidated intermediate and advanced tutorials and added to the contributing guide that new tutorials should go in examples/tutorials/advanced, since we have the beginner topics pretty well covered.

@willschlitzer
Copy link
Contributor

Should we put "Tutorials" at the top of the "User Guide" section? That would be my pick; I think it should be at the top of the section.

@seisman seisman added this to the 0.6.0 milestone Nov 6, 2021
Copy link
Member

@seisman seisman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.

@seisman seisman added the final review call This PR requires final review and approval from a second reviewer label Nov 6, 2021
Copy link
Member

@weiji14 weiji14 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @meghanrjones! Just some comments.

examples/tutorials/README.txt Outdated Show resolved Hide resolved
examples/tutorials/beginner/README.txt Outdated Show resolved Hide resolved
Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
@seisman
Copy link
Member

seisman commented Nov 12, 2021

Can we merge this PR now?

Copy link
Member

@weiji14 weiji14 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes please, go for it!

@seisman seisman merged commit f228cdf into main Nov 14, 2021
@seisman seisman deleted the reorganize-tutorial-sidebar branch November 14, 2021 09:05
@seisman seisman removed the final review call This PR requires final review and approval from a second reviewer label Nov 14, 2021
sixy6e pushed a commit to sixy6e/pygmt that referenced this pull request Dec 21, 2022
…ingTools#1603)

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
This pull request was closed.
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Redesign the tutorial section on the documentation sidebar
5 participants