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.

Sign up for GitHub

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

Jump to bottom

Fix documentation #3554

Merged
merged 1 commit into from
Nov 21, 2019
Merged

Fix documentation #3554

merged 1 commit into from
Nov 21, 2019

Conversation

keewis
Copy link
Collaborator

@keewis keewis commented Nov 20, 2019

It seems we introduced a warning in whats-new.rst and we dropped Dataset.drop and DataArray.drop from the documentation (which were only deprecated).

xref #3552

  • Passes black . && mypy . && flake8

@keewis
Copy link
Collaborator Author

keewis commented Nov 20, 2019

the docs fail because it cannot find a rasterio / tif file. Does anyone know if that is a random / network error or if something broke?

@keewis
Copy link
Collaborator Author

keewis commented Nov 20, 2019

@max-sixty, what do you think about re-adding the parameter / returns sections of drop?

@max-sixty
Copy link
Collaborator

My thought behind removing drop was to only list methods that we recommend people use. We're keeping drop for back-compat reasons, but I wouldn't recommend anyone who is creating new code use it.

But maybe that's too aggressive. Any thoughts anyone?

@max-sixty
Copy link
Collaborator

the docs fail because it cannot find a rasterio / tif file.

Hmmm, I haven't seen that before. Do you know whether it fails on master? (I can check too)

@dcherian
Copy link
Contributor

dcherian commented Nov 20, 2019 •
edited
Loading

Here's the error

rasterio.errors.RasterioIOError: '/vsicurl/https://github.com/mapbox/rasterio/raw/master/tests/data/RGB.byte.tif' does not exist in the file system, and is not recognized as a supported dataset name.

That URL does work. The /vsicurl/ is screwing it up?

I think our efforts may be better spent getting the scipy19-docs branch to work because that migrates the gallery .py scripts to notebooks.

@keewis
Copy link
Collaborator Author

keewis commented Nov 20, 2019

Is the problem there still that readthedocs fails but CI works, isn't it?

@max-sixty, I think it should be fine as long as the deprecation is visible enough, but we could also add it to api-hidden.rst which would make the documentation page generate without adding it to api.rst

@dcherian
Copy link
Contributor

Is the problem there still that readthedocs fails but CI works, isn't it?

👍

@jthielen
Copy link
Contributor

But maybe that's too aggressive. Any thoughts anyone?

I'd like to have documentation available for anything in the public API, so that it can be a useful reference for both previously existing and new code. I think for deprecated functionality it makes the most sense to keep the docs, but warn prominently that it should not be used in new code (e.g. https://unidata.github.io/MetPy/dev/api/generated/metpy.calc.html#deprecated)?

@keewis
Copy link
Collaborator Author

keewis commented Nov 20, 2019

@dcherian: should I prepare a merge PR so we can make progress on that?

@dcherian
Copy link
Contributor

@keewis Yes please! We might have to iterate on RTD. Do you have an RTD build set up already? If not, see #3369

@keewis
Copy link
Collaborator Author

keewis commented Nov 20, 2019

I do, but the builds currently choke on conda taking too much memory. Let's discuss that in #3557.

@max-sixty
Copy link
Collaborator

I'd like to have documentation available for anything in the public API, so that it can be a useful reference for both previously existing and new code. I think for deprecated functionality it makes the most sense to keep the docs, but warn prominently that it should not be used in new code (e.g. https://unidata.github.io/MetPy/dev/api/generated/metpy.calc.html#deprecated)?

I think this is a pretty good balance, i.e. a section with Deprecated / Pending Deprecation. If we can do that as part of this then great; otherwise I'm happy to have a go

@keewis
Copy link
Collaborator Author

keewis commented Nov 21, 2019 •
edited
Loading

@max-sixty, I'm probably too occupied with #3557 to do this anytime soon, so go ahead if you want to (I'll remove the drop related changes).

@keewis
Copy link
Collaborator Author

keewis commented Nov 21, 2019

I removed the drop related changes, so we can merge?

@dcherian dcherian merged commit 9717681 into pydata:master Nov 21, 2019
@keewis keewis deleted the fix-documentation branch November 22, 2019 00:19
@max-sixty max-sixty mentioned this pull request Nov 22, 2019
Merged
dcherian added a commit to dcherian/xarray that referenced this pull request Nov 25, 2019
@dcherian
Merge remote-tracking branch 'upstream/master' into fix/plot-broadcast
794939e 
* upstream/master:
  Add drop to api.rst under pending deprecations (pydata#3561)
  replace duplicate method _from_vars_and_coord_names (pydata#3565)
  propagate indexes in to_dataset, from_dataset (pydata#3519)
  Switch examples to notebooks + scipy19 docs improvements (pydata#3557)
  fix whats-new.rst (pydata#3554)
dcherian added a commit to dcherian/xarray that referenced this pull request Dec 4, 2019
@dcherian
Merge remote-tracking branch 'upstream/master' into coarsen-reduce
d592623 
* upstream/master: (22 commits)
  Resolve the version issues on RTD (pydata#3589)
  Add bottleneck & rasterio git tip to upstream-dev CI (pydata#3585)
  update whats-new.rst (pydata#3581)
  Examples for quantile (pydata#3576)
  add cftime intersphinx entries (pydata#3577)
  Add pyXpcm to Related Projects doc page (pydata#3578)
  Reimplement quantile with apply_ufunc (pydata#3559)
  add environment file for binderized examples (pydata#3568)
  Add drop to api.rst under pending deprecations (pydata#3561)
  replace duplicate method _from_vars_and_coord_names (pydata#3565)
  propagate indexes in to_dataset, from_dataset (pydata#3519)
  Switch examples to notebooks + scipy19 docs improvements (pydata#3557)
  fix whats-new.rst (pydata#3554)
  Tweaks to release instructions (pydata#3555)
  Clarify conda environments for new contributors (pydata#3551)
  Revert to dev version
  0.14.1 whatsnew (pydata#3547)
  sparse option to reindex and unstack (pydata#3542)
  Silence sphinx warnings (pydata#3516)
  Numpy 1.18 support (pydata#3537)
  ...
dcherian added a commit to dcherian/xarray that referenced this pull request Dec 5, 2019
@dcherian
Merge remote-tracking branch 'upstream/master' into fix/user-coordinates
77c7c0f 
* upstream/master: (35 commits)
  fix plotting with transposed nondim coords. (pydata#3441)
  make coarsen reductions consistent with reductions on other classes (pydata#3500)
  Resolve the version issues on RTD (pydata#3589)
  Add bottleneck & rasterio git tip to upstream-dev CI (pydata#3585)
  update whats-new.rst (pydata#3581)
  Examples for quantile (pydata#3576)
  add cftime intersphinx entries (pydata#3577)
  Add pyXpcm to Related Projects doc page (pydata#3578)
  Reimplement quantile with apply_ufunc (pydata#3559)
  add environment file for binderized examples (pydata#3568)
  Add drop to api.rst under pending deprecations (pydata#3561)
  replace duplicate method _from_vars_and_coord_names (pydata#3565)
  propagate indexes in to_dataset, from_dataset (pydata#3519)
  Switch examples to notebooks + scipy19 docs improvements (pydata#3557)
  fix whats-new.rst (pydata#3554)
  Tweaks to release instructions (pydata#3555)
  Clarify conda environments for new contributors (pydata#3551)
  Revert to dev version
  0.14.1 whatsnew (pydata#3547)
  sparse option to reindex and unstack (pydata#3542)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@keewis @max-sixty @dcherian @jthielen