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

Improve docstring of x2sys_init and x2sys_cross #930

Merged
merged 12 commits into from
Feb 20, 2021

Conversation

maxrjones
Copy link
Member

@maxrjones maxrjones commented Feb 19, 2021

Description of proposed changes

This fixes the bullet list in the speed parameter description in the x2sys_cross docs in order to suppress this sphinx build warning:

pygmt/pygmt/x2sys.py:docstring of pygmt.x2sys.x2sys_cross:93: WARNING: Bullet list ends without a blank line; unexpected unindent.

Fixes #

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

@maxrjones maxrjones added bug Something isn't working documentation Improvements or additions to documentation skip-changelog Skip adding Pull Request to changelog labels Feb 19, 2021
pygmt/x2sys.py Outdated Show resolved Hide resolved
@seisman
Copy link
Member

seisman commented Feb 19, 2021

I see more tiny issues in the x2sys_cross documentation. Do you want to also fix those tiny issues in this PR?

@seisman seisman added this to the 0.3.1 milestone Feb 19, 2021
@maxrjones
Copy link
Member Author

I see more tiny issues in the x2sys_cross documentation. Do you want to also fix those tiny issues in this PR?

Sure, I can do that.

Co-authored-by: Dongdong Tian <[email protected]>
@seisman seisman marked this pull request as draft February 19, 2021 01:34
@seisman
Copy link
Member

seisman commented Feb 19, 2021

I just converted this PR to draft to save CI resources.

@maxrjones
Copy link
Member Author

@seisman, is there a reason for this module to be in pygmt/, in contrast to the other modules which are in pygmt/src?

@seisman
Copy link
Member

seisman commented Feb 19, 2021

It should be in src/, but we haven't decided if we want x2sys_init and x2sys_cross in one file src/x2sys.py, or two files src/x2sys_init.py and src/x2sys_cross.py.

See #832 (comment) and #807 (comment).

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.

It should be in src/, but we haven't decided if we want x2sys_init and x2sys_cross in one file src/x2sys.py, or two files src/x2sys_init.py and src/x2sys_cross.py.

See #832 (comment) and #807 (comment).

Just on this, maybe better to have them in two separate files, since there are other x2sys_* modules too which may need to be wrapped in the future. Do we want to do the x2sys move before, during, or after this PR?

pygmt/x2sys.py Show resolved Hide resolved
@maxrjones
Copy link
Member Author

It should be in src/, but we haven't decided if we want x2sys_init and x2sys_cross in one file src/x2sys.py, or two files src/x2sys_init.py and src/x2sys_cross.py.
See #832 (comment) and #807 (comment).

Just on this, maybe better to have them in two separate files, since there are other x2sys_* modules too which may need to be wrapped in the future. Do we want to do the x2sys move before, during, or after this PR?

I agree about separate files and would prefer making that change during or after this PR to avoid conflicts and extra effort.

@weiji14
Copy link
Member

weiji14 commented Feb 19, 2021

Just on this, maybe better to have them in two separate files, since there are other x2sys_* modules too which may need to be wrapped in the future. Do we want to do the x2sys move before, during, or after this PR?

I agree about separate files and would prefer making that change during or after this PR to avoid conflicts and extra effort.

Before or after? I can do one before but you'll need to resolve some merge conflicts, or I can open one after this one is merged. I presume this PR is basically done already?

@maxrjones
Copy link
Member Author

Just on this, maybe better to have them in two separate files, since there are other x2sys_* modules too which may need to be wrapped in the future. Do we want to do the x2sys move before, during, or after this PR?

I agree about separate files and would prefer making that change during or after this PR to avoid conflicts and extra effort.

Before or after? I can do one before but you'll need to resolve some merge conflicts, or I can open one after this one is merged. I presume this PR is basically done already?

I realize now my language was confusing. By 'during' I really meant 'as part of', but in remembering the 'keep PR's small' policy it seems after is best. As far as I can tell this PR is done.

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.

Ok, I had a look through the rendered x2sys_init and x2sys_cross API docs and they seem fine. Though best if @seisman can approve too since he has a better eye on the bold/italics/code-blocks matter.

pygmt/x2sys.py Show resolved Hide resolved
pygmt/x2sys.py Show resolved Hide resolved
pygmt/x2sys.py Outdated Show resolved Hide resolved
pygmt/x2sys.py Show resolved Hide resolved
pygmt/x2sys.py Show resolved Hide resolved
pygmt/x2sys.py Show resolved Hide resolved
Co-authored-by: Dongdong Tian <[email protected]>
pygmt/x2sys.py Outdated Show resolved Hide resolved
pygmt/x2sys.py Outdated Show resolved Hide resolved
@seisman
Copy link
Member

seisman commented Feb 20, 2021

/format

1 similar comment
@maxrjones
Copy link
Member Author

/format

@maxrjones maxrjones marked this pull request as ready for review February 20, 2021 00:53
@seisman
Copy link
Member

seisman commented Feb 20, 2021

@meghanrjones /format and make format sometimes don't work well for docstrings. You may have to do it manually.

@maxrjones
Copy link
Member Author

All lines locally appear to be 79 characters or less and my branch is up to date. Should I request a re-run on the style checks?

@seisman
Copy link
Member

seisman commented Feb 20, 2021

Lines 297 and 298 are too long.

pygmt/x2sys.py:297:80: W505 doc line too long (83 > 79 characters)
pygmt/x2sys.py:298:80: W505 doc line too long (81 > 79 characters)

@seisman seisman changed the title Fix list in x2sys_cross docstring Improve docstring of x2sys_init and x2sys_cross Feb 20, 2021
@seisman seisman removed the bug Something isn't working label Feb 20, 2021
@seisman seisman added skip-changelog Skip adding Pull Request to changelog and removed skip-changelog Skip adding Pull Request to changelog labels Feb 20, 2021
@seisman seisman merged commit 5a4731f into GenericMappingTools:master Feb 20, 2021
@maxrjones maxrjones deleted the docs-x2sys branch February 20, 2021 16:13
sixy6e pushed a commit to sixy6e/pygmt that referenced this pull request Dec 21, 2022
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 skip-changelog Skip adding Pull Request to changelog
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants