[DOC] Add developer documentation page

[bellet]

To make it easier for newcomers to start contributing to metric-learn, we should a developer page in the doc. This page should explain things like how to start contributing, how to compile the doc locally, etc. We could borrow ideas from https://scikit-learn.org/stable/developers/contributing.html

[wdevazelhes]

Here is a quick comment on what to do for a release (first draft, some things might be missing but I'll try to be inclusive):

Things to check before the release:

• That all versions numbers are updated: in metric_learn/_version.py, and in doc/conf.py
• That the final year date in doc/conf.py after "copyright" is the right one (e.g. 2020)

Release:

• On github, click on "draft a new release" here: https://github.com/scikit-learn-contrib/metric-learn/releases, draft the release (you can look in the link at the commits made since the last release to help write the message of the release). Then click on "Publish release" (it will automatically add the files needed)

• Run the following commands in the repo in a local terminal: this will push the repo to PyPi (you need an account on PyPi)

  $ python3 setup.py sdist
  $ python3 setup.py bdist_wheel
  $ twine upload dist/*

• Normally after a few minutes you should see that the badge on the README.rst gets updated with the new version, also the version is available if you search for it on PyPi.

• For the docs: You need to be able to compile the docs. For that you need an environment with installed:

  • sphinx, sphinx-gallery, pillow, sphinx-rtd-theme, matplotlib, maybe sth else ? (install whatever needed by the warnings...)
  • metric-learn installed in editable mode (run pip install -e . in the metric-learn repo) (should install also the deps like numpy, scipy, sklearn)
  • then cd doc
  • then sudo rm -r generated _build auto_examples (make sure there is no old files from previous builds)
  • then run make html. Check that the doc is well generated (the index page is in doc/_build/html/index.html)
  • then copy in clipboard everything that is inside doc/_build/html/*
  • then go on the branch gh-pages of metric-learn and replace all the files by what you have copied, and push. This will automatically update the page in a few minutes. You can check at the page for the docs that it works.

• For conda: @bellet maybe you want to fill in here ?

[bellet]

Thanks. For conda-forge there is not much to do, a PR is automatically created in the feedstock repo https://github.com/conda-forge/metric-learn-feedstock If requirements, license, etc have not changed, the recipe automatically generated by the bot should be correct. Otherwise one can edit it and directly push to the PR, see https://conda-forge.org/docs/maintainer/updating_pkgs.html Then merging the PR (which requires to be identified as a maintainer of the feedstock) will make the release. If it is not visible on https://anaconda.org/conda-forge/metric-learn One can do an empty commit to master to trigger the update

[terrytangyuan]

One suggestion: instead of releasing directly from master, we can consider doing the following:

1. Create branch v0.1.0-release from master that includes all changes mentioned above, e.g. version number, etc.
2. Turn this branch into protected branch.
3. Create a release v0.1.0-rc0 ("rc" stands for release candidate) from this branch v0.1.0-release via GitHub UI here and mark it as pre-release.
4. Give the community some time (e.g. 1-2 weeks) to test the release candidate.
5. If there are any bug fixes, we push to v0.1.0-release branch and then release v0.1.0-rc1.
6. Once we are confident, we create a stable release v0.1.0, build the package wheels, and then publish the package v0.1.0 to PyPI

If there are any critical bug fixes/patches, we can still cherry-pick and backport the changes to v0.1.0-release or any past release branches.