Improvements to Docs for new contributors #19344

ianhi · 2021-01-23T06:04:06Z

PR Summary

At least I think they are improvements. I tried to go through the process as if I didn't know and was starting by clicking the contributing tab. These changes address the areas where I felt I would have gotten stuck or knocked off course.

See also: https://discourse.matplotlib.org/t/contributor-onboarding-retention/21714

I tried to make granular commits and leave explanations in the body of the commit messages.

PR Checklist

Is Flake 8 compliant (run flake8 on changed files to check).
Documentation is sphinx and numpydoc compliant (the docs should build without error).

aitikgupta

Since we're installing the editable local version, should we also mention something about it?

aitikgupta · 2021-01-23T06:30:44Z

doc/devel/contributing.rst


-4. Create a branch to hold your changes::
+      cd matplotlib
+      pip install -ve . 


Suggested change

pip install -ve .

pip install -ve .

NOTE: `-e` flag would make your installation 'editable', such that your work is always

in sync as the installed version. For more details see [ref](https://pip.pypa.io/en/stable/reference/pip_install/#install-editable).

I think this resolved by entirely deferring this to the standalone dev install page

timhoffm · 2021-01-23T13:07:30Z

doc/devel/contributing.rst

+4. Enter the directory and install the local version of Matplotlib. For more
+   detailed instructions on doing this see ref`<installing_for_devs>`::

-4. Create a branch to hold your changes::
+      cd matplotlib
+      pip install -ve . 


This is only half the truth. It's important to set up a dedicated environment (venv or conda) for development and do the editable install there. Otherwise people will corrupt their standard python environment.

I suggest not giving any details here but completely deferring to :ref:`installing_for_devs` .

doc/devel/contributing.rst

doc/devel/index.rst

ianhi · 2021-02-04T03:06:16Z

Thank you for the reviews - I think I have address all of them. And sorry for the two week wait, it's amazing how a few emails can really make quite a lot of work materialize :P

ianhi · 2021-02-04T16:22:26Z

I think the doc failures are unrelated:


Unexpected failing examples:
/home/circleci/project/examples/units/ellipse_with_units.py failed leaving traceback:
Traceback (most recent call last):
  File "/home/circleci/project/examples/units/ellipse_with_units.py", line 33, in <module>
    x, y = np.dot(R, [x, y])
  File "<__array_function__ internals>", line 5, in dot
FutureWarning: The input object of type 'TaggedValue' is an array-like implementing one of the corresponding protocols (`__array__`, `__array_interface__` or `__array_struct__`); but not a sequence (or 0-D). In the future, this object will be coerced as if it was first converted using `np.array(obj)`. To retain the old behaviour, you have to either modify the type 'TaggedValue', or assign to an empty array created with `np.empty(correct_shape, dtype=object)`.


/home/circleci/project/examples/units/radian_demo.py failed leaving traceback:
Traceback (most recent call last):
  File "/home/circleci/project/examples/units/radian_demo.py", line 26, in <module>
    axs[0].plot(x, cos(x), xunits=radians)
  File "/home/circleci/project/lib/matplotlib/axes/_axes.py", line 1605, in plot
    lines = [*self._get_lines(*args, data=data, **kwargs)]
  File "/home/circleci/project/lib/matplotlib/axes/_base.py", line 315, in __call__
    yield from self._plot_args(this, kwargs)
  File "/home/circleci/project/lib/matplotlib/axes/_base.py", line 490, in _plot_args
    x = _check_1d(xy[0])
  File "/home/circleci/project/lib/matplotlib/cbook/__init__.py", line 1328, in _check_1d
    return np.atleast_1d(x)
  File "<__array_function__ internals>", line 5, in atleast_1d
  File "/home/circleci/.local/lib/python3.8/site-packages/numpy/core/shape_base.py", line 66, in atleast_1d
    ary = asanyarray(ary)
  File "/home/circleci/.local/lib/python3.8/site-packages/numpy/core/_asarray.py", line 171, in asanyarray
    return array(a, dtype, copy=False, order=order, subok=True)
FutureWarning: The input object of type 'TaggedValue' is an array-like implementing one of the corresponding protocols (`__array__`, `__array_interface__` or `__array_struct__`); but not a sequence (or 0-D). In the future, this object will be coerced as if it was first converted using `np.array(obj)`. To retain the old behaviour, you have to either modify the type 'TaggedValue', or assign to an empty array created with `np.empty(correct_shape, dtype=object)`.


-------------------------------------------------------------------------------

Extension error:
Here is a summary of the problems encountered when running the examples

Unexpected failing examples:
/home/circleci/project/examples/units/ellipse_with_units.py failed leaving traceback:
Traceback (most recent call last):
  File "/home/circleci/project/examples/units/ellipse_with_units.py", line 33, in <module>
    x, y = np.dot(R, [x, y])
  File "<__array_function__ internals>", line 5, in dot
FutureWarning: The input object of type 'TaggedValue' is an array-like implementing one of the corresponding protocols (`__array__`, `__array_interface__` or `__array_struct__`); but not a sequence (or 0-D). In the future, this object will be coerced as if it was first converted using `np.array(obj)`. To retain the old behaviour, you have to either modify the type 'TaggedValue', or assign to an empty array created with `np.empty(correct_shape, dtype=object)`.


/home/circleci/project/examples/units/radian_demo.py failed leaving traceback:
Traceback (most recent call last):
  File "/home/circleci/project/examples/units/radian_demo.py", line 26, in <module>
    axs[0].plot(x, cos(x), xunits=radians)
  File "/home/circleci/project/lib/matplotlib/axes/_axes.py", line 1605, in plot
    lines = [*self._get_lines(*args, data=data, **kwargs)]
  File "/home/circleci/project/lib/matplotlib/axes/_base.py", line 315, in __call__
    yield from self._plot_args(this, kwargs)
  File "/home/circleci/project/lib/matplotlib/axes/_base.py", line 490, in _plot_args
    x = _check_1d(xy[0])
  File "/home/circleci/project/lib/matplotlib/cbook/__init__.py", line 1328, in _check_1d
    return np.atleast_1d(x)
  File "<__array_function__ internals>", line 5, in atleast_1d
  File "/home/circleci/.local/lib/python3.8/site-packages/numpy/core/shape_base.py", line 66, in atleast_1d
    ary = asanyarray(ary)
  File "/home/circleci/.local/lib/python3.8/site-packages/numpy/core/_asarray.py", line 171, in asanyarray
    return array(a, dtype, copy=False, order=order, subok=True)
FutureWarning: The input object of type 'TaggedValue' is an array-like implementing one of the corresponding protocols (`__array__`, `__array_interface__` or `__array_struct__`); but not a sequence (or 0-D). In the future, this object will be coerced as if it was first converted using `np.array(obj)`. To retain the old behaviour, you have to either modify the type 'TaggedValue', or assign to an empty array created with `np.empty(correct_shape, dtype=object)`.

QuLogic · 2021-02-04T21:43:17Z

If you rebase, it will fix that docs problem.

+ Reword contributing opening paragraph Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

also remove the $ as they make it more difficult for readers to copy paste link to more detailed dev install instructions only link to install page in brief set up docs.

it seems to pair well with the contributor incubator part, and it was somewhat hard to notice where it used to be.

Less mental effort to read this, as no time spent thinking about how different your versions are.

It's super easy to click on that link and then get bogged down in details rather than read the short guide that follows that paragraph.

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

timhoffm · 2021-02-05T01:30:01Z

Thanks @ianhi!

aitikgupta reviewed Jan 23, 2021

View reviewed changes

timhoffm reviewed Jan 23, 2021

View reviewed changes

ianhi and others added 6 commits February 4, 2021 16:54

add a header paragraph to the top level contributing tab

7941c36

+ Reword contributing opening paragraph Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

add install step to the Contributing code

297070a

also remove the $ as they make it more difficult for readers to copy paste link to more detailed dev install instructions only link to install page in brief set up docs.

move issues for new contributors higher up on the page

bae3bad

it seems to pair well with the contributor incubator part, and it was somewhat hard to notice where it used to be.

update the versions to modern versions

98971ac

Less mental effort to read this, as no time spent thinking about how different your versions are.

Remove early link to gitwash and place description in the see also

ea230e3

It's super easy to click on that link and then get bogged down in details rather than read the short guide that follows that paragraph.

Clarify description of good first issues

7965576

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

ianhi force-pushed the docs branch from 7980e4a to 7965576 Compare February 4, 2021 21:54

timhoffm approved these changes Feb 5, 2021

View reviewed changes

timhoffm added the Documentation label Feb 5, 2021

timhoffm added this to the v3.4.0 milestone Feb 5, 2021

timhoffm merged commit 0724d39 into matplotlib:master Feb 5, 2021

ianhi deleted the docs branch February 5, 2021 02:14

ianhi mentioned this pull request Feb 5, 2021

Use absolute link for discourse #19457

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to Docs for new contributors #19344

Improvements to Docs for new contributors #19344

ianhi commented Jan 23, 2021

aitikgupta left a comment •

edited

Loading

aitikgupta Jan 23, 2021

ianhi Feb 4, 2021

timhoffm Jan 23, 2021

ianhi commented Feb 4, 2021 •

edited

Loading

ianhi commented Feb 4, 2021

QuLogic commented Feb 4, 2021

timhoffm commented Feb 5, 2021

Improvements to Docs for new contributors #19344

Improvements to Docs for new contributors #19344

Conversation

ianhi commented Jan 23, 2021

PR Summary

PR Checklist

aitikgupta left a comment • edited Loading

Choose a reason for hiding this comment

aitikgupta Jan 23, 2021

Choose a reason for hiding this comment

ianhi Feb 4, 2021

Choose a reason for hiding this comment

timhoffm Jan 23, 2021

Choose a reason for hiding this comment

ianhi commented Feb 4, 2021 • edited Loading

ianhi commented Feb 4, 2021

QuLogic commented Feb 4, 2021

timhoffm commented Feb 5, 2021

aitikgupta left a comment •

edited

Loading

ianhi commented Feb 4, 2021 •

edited

Loading