8000 DOC: reorganize and simplify contributing.rst by tacaswell · Pull Request #7699 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: reorganize and simplify contributing.rst #7699

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

Merged
merged 6 commits into from
Jan 5, 2017
+52 −45
Merged

DOC: reorganize and simplify contributing.rst #7699

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fc5dcf4
DOC: reorganize and simplify contributing.rst
tacaswell Dec 29, 2016
600544c
DOC: ensure local variables are defined
tacaswell Dec 31, 2016
de50bfa
DOC: bit more accurate how develop mode works
tacaswell Dec 31, 2016
03111bf
DOC: standardize on Matplotlib
tacaswell Dec 31, 2016
534b832
DOC: minor tweaks to wording + capitalization
tacaswell Jan 5, 2017
39f8798
DOC: fix typo
tacaswell Jan 5, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
DOC: reorganize and simplify contributing.rst 
 - only provide one installation direction
 - put details about local testing at the top
  • Loading branch information
@tacaswell
tacaswell committed Dec 31, 2016
commit fc5dcf4827a13038e54d877dc2336dc672373f9c
64 changes: 35 additions & 29 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,44 +21,62 @@ also welcome to post feature requests or pull requests.
Retrieving and installing the latest version of the code
========================================================

When working on the Matplotlib source, setting up a `virtual
environment
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a
`conda environment <http://conda.pydata.org/docs/using/envs.html>`_ is
recommended.

.. warning::

If you already have a version of matplotlib installed, you will need to
Copy link
Member

Choose a reason for hiding this comment

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

Matplotlib

uninstall it.
Copy link
Contributor

Choose a reason for hiding this comment

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

Only in the same venv, I think? AFAICT that looks big and scary while it is simply not true if the instructions above are followed :-)

Copy link
Member Author

Choose a reason for hiding this comment

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

You can drive your self to very strange situations with overlapping installs, but will re-word this to be a bit less scary.


We use `Git <https://git-scm.com/>`_ for version control and
`GitHub <https://github.com/>`_ for hosting our main repository.

You can check out the latest sources with the command::
You can check out the latest sources with the command (see
:ref:`set-up-fork` for more details)::

git clone git@github.com:matplotlib/matplotlib.git

and navigate to the matplotlib directory.
Copy link
Member

Choose a reason for hiding this comment

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

Matplotlib


After obtaining a local copy of the matplotlib source code (:ref:`set-up-fork`),
navigate to the matplotlib directory and run the following in the shell::
To make sure the tests run locally you must build against the correct version
of freetype. To configure the build system to fetch and build it either export
the env ``MPLLOCALFREETYPE`` as::

python setup.py develop
export MPLLOCALFREETYPE=1

or::
or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit to contain ::

pip install -v -e .
[test]
local_freetype = True


This installs matplotlib for development (i.e., builds everything and places the
symbolic links back to the source code).
To install Matplotlib (and compile the c-extensions) run the following
command from the top-level directory ::

.. warning::
pip install -v -e ./

If you already have a version of matplotlib installed, you will need to
uninstall it.
This installs Matplotlib in 'editable/develop mode', i.e.,
builds everything and places symbolic links back to the source code
Copy link
Member

Choose a reason for hiding this comment

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

I don't think the symbolic link statement is true anymore. It adds a file in which the path to the library is written, and the path is explored at runtime.
(as I don't understand anything about the way python packaging is done, you should take this claim with a grain of salt…)

Copy link
Member Author

Choose a reason for hiding this comment

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

I think you are right....

from the install directory. Thus, any changes to the ``*.py`` files
will be reflected the next time you import the library. If you change
the c-extension source (which might happen if you change branches) you
will need to run::

python setup.py build

.. note::
or re-run ``pip install -v -e ./``.

If you decide to do install with ``python setup.py develop`` or ``pip
install -v -e``, you will have to rerun::

python setup.py build
Alternatively, if you do ::

every time the source code of a compiled extension is changed (for
instance when switching branches or pulling changes from upstream).
pip install -v ./

all of the files will be copied to the installation directory however,
you will have to rerun this command every time the source is changed.


You can then run the tests to check your work environment is set up properly::
Expand All @@ -75,18 +93,6 @@ You can then run the tests to check your work environment is set up properly::
<https://docs.python.org/dev/library/unittest.mock.html>`_ (if python < 3.3), `Ghostscript
<https://www.ghostscript.com/>`_, `Inkscape <https://inkscape.org>`_

.. note:: To make sure the tests run locally:

* Copy setup.cfg.template to setup.cfg
* Edit setup.cfg to set ``test`` to True, and ``local_freetype`` to True
* If you have built matplotlib previously, remove the ``build`` folder.
* Execute the build command.

When working on bleeding edge packages, setting up a
`virtual environment
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ or a `conda
environment <http://conda.pydata.org/docs/using/envs.html>`_ is recommended.

.. seealso::

* :ref:`testing`
Expand Down
0