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

Apply blackdoc to the documentation #4012

Merged
merged 6 commits into from
Apr 29, 2020
Merged

Apply blackdoc to the documentation #4012

merged 6 commits into from
Apr 29, 2020

Conversation

keewis
Copy link
Collaborator

@keewis keewis commented Apr 27, 2020 •
edited
Loading

This applies black to the code in the documentation using blackdoc. The tool itself is not stable or released yet, but this demonstrate the upcoming support for rst code blocks, including the ipython sphinx directive. There are a few issues with the latter, e.g. the semi-colon to suppress output will be removed by black. In a few cases this changes the other outputs, mostly plots. I think we might fix/work around that by moving the line decorator to the last line that should be plotted (which is what I did), but we could also use the ipython syntax with cell decorators:

@savefig ...
In [1]: # code
   ...: # with multiple lines

Also, while I checked the changes manually, please don't take my word for it: I'm really not sure I didn't miss anything. I know this is a rather large PR so I'm fine with waiting.

  • Passes isort -rc . && black . && mypy . && flake8
  • Fully documented, including whats-new.rst for all changes and api.rst for new API

@crusaderky
Copy link
Contributor

LGTM - can't wait for the tool to mature!

crusaderky
crusaderky reviewed Apr 28, 2020
View reviewed changes
doc/computation.rst

Calculate the weighted sum:

.. ipython:: python

weighted_prec.sum()
weighted_prec.sum()
Copy link
Contributor

Choose a reason for hiding this comment

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

The RST reference (https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html) dictates a 3-spaces indentation for multi-line .. blocks. However I appreciate the frustration in not being to use the Tab key. Was it a conscious decision?

Copy link
Collaborator Author

@keewis keewis Apr 28, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

no, not really. I was using 4 spaces since that's the indent in the python code. Actually, the tool only makes sure there is a consistent indentation depth (it enforces the indentation of the code).

If you look at the reference, though, the 3-spaces indentation is only implicitly mentioned in the syntax diagram:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

but not in the text, it only says:

The directive block [...] consists of any text on the first line of the directive after the directive marker, and any subsequent indented text.

So I'd assume 3 spaces is not mandatory (and sphinx doesn't really care about the indentation depth).

@crusaderky
Copy link
Contributor

I went through everything and it seems all fine.
I'm happy to merge as soon as you add a line to the What's New

@keewis
Copy link
Collaborator Author

keewis commented Apr 28, 2020

done

@dcherian
Copy link
Contributor

Thanks @keewis & @crusaderky

I went through everything and it seems all fine.

Wow!

@DocOtak
Copy link
Contributor

DocOtak commented Apr 28, 2020

I really like what it did to some of the long xr.Dataset() and xr.DataArray() calls. Very readable!

@max-sixty
Copy link
Collaborator

Great job @keewis !

@dcherian dcherian merged commit 8834afa into pydata:master Apr 29, 2020
@keewis keewis deleted the apply-blackdoc branch April 29, 2020 16:20
dcherian added a commit to dcherian/xarray that referenced this pull request May 1, 2020
@dcherian
Merge remote-tracking branch 'upstream/master' into map-blocks-schema
085ce9a 
* upstream/master: (39 commits)
  Pint support for DataArray (pydata#3643)
  Apply blackdoc to the documentation (pydata#4012)
  ensure Variable._repr_html_ works (pydata#3973)
  Fix handling of abbreviated units like msec (pydata#3998)
  full_like: error on non-scalar fill_value (pydata#3979)
  Fix some code quality and bug-risk issues (pydata#3999)
  DOC: add pandas.DataFrame.to_xarray (pydata#3994)
  Better chunking error messages for zarr backend (pydata#3983)
  Silence sphinx warnings (pydata#3990)
  Fix distributed tests on upstream-dev (pydata#3989)
  Add multi-dimensional extrapolation example and mention different behavior of kwargs in interp (pydata#3956)
  keep attrs in interpolate_na (pydata#3970)
  actually use preformatted text in the details summary (pydata#3978)
  facetgrid: Ensure that colormap params are only determined once. (pydata#3915)
  RasterioDeprecationWarning (pydata#3964)
  Empty line missing for DataArray.assign_coords doc (pydata#3963)
  New coords to existing dim (doc) (pydata#3958)
  implement a more threadsafe call to colorbar (pydata#3944)
  Fix wrong order of coordinate converted from pd.series with MultiIndex (pydata#3953)
  Updated list of core developers (pydata#3943)
  ...
dcherian added a commit to kmuehlbauer/xarray that referenced this pull request May 9, 2020
@dcherian
Merge remote-tracking branch 'upstream/master' into fix-idxminmax-das…
20ccf5a 
…k-issues

* upstream/master: (22 commits)
  support darkmode (pydata#4036)
  Use literal syntax instead of function calls to create the data structure (pydata#4038)
  Add template xarray object kwarg to map_blocks (pydata#3816)
  Transpose coords by default (pydata#3824)
  Remove broken test for Panel with to_pandas() (pydata#4028)
  Allow warning with cartopy in docs plotting build (pydata#4032)
  Support overriding existing variables in to_zarr() without appending (pydata#4029)
  chore: Remove unnecessary comprehension (pydata#4026)
  fix to_netcdf docstring typo (pydata#4021)
  Pint support for DataArray (pydata#3643)
  Apply blackdoc to the documentation (pydata#4012)
  ensure Variable._repr_html_ works (pydata#3973)
  Fix handling of abbreviated units like msec (pydata#3998)
  full_like: error on non-scalar fill_value (pydata#3979)
  Fix some code quality and bug-risk issues (pydata#3999)
  DOC: add pandas.DataFrame.to_xarray (pydata#3994)
  Better chunking error messages for zarr backend (pydata#3983)
  Silence sphinx warnings (pydata#3990)
  Fix distributed tests on upstream-dev (pydata#3989)
  Add multi-dimensional extrapolation example and mention different behavior of kwargs in interp (pydata#3956)
  ...
@keewis keewis mentioned this pull request May 16, 2020
Merged
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@crusaderky crusaderky crusaderky approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@keewis @crusaderky @dcherian @DocOtak @max-sixty