wassname/ray
1
0
Fork 0
mirror of https://github.com/wassname/ray.git synced 2026-09-09 11:32:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

[tune] Update API Reference Page (#7671)

Browse Source 
* widerdocs

* init

* docs

* fix

* moveit

* mix

* better_docs

* remove

* Apply suggestions from code review

Co-Authored-By: Sven Mika <sven@anyscale.io>

Co-authored-by: Sven Mika <sven@anyscale.io>
This commit is contained in:
Richard Liaw
2020-03-22 16:42:20 -07:00
committed by GitHub
co-authored by Sven Mika
parent 288933ec6b
commit 81d311031b
27 changed files with 744 additions and 394 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/_static/css/custom.css
+21
View File
@@ -0,0 +1,21 @@
/* Max window size */
.wy-nav-content{
max-width: 1000px;
}
/*Extends the docstring signature box.*/
.rst-content dl:not(.docutils) dt {
display: block;
padding: 10px;
word-wrap: break-word;
padding-right: 100px;
}
/*Lists in an admonition note do not have awkward whitespace below.*/
.rst-content .admonition-note .section ul {
margin-bottom: 0px
}
/*Properties become blue (classmethod, staticmethod, property)*/
.rst-content dl dt em.property {
color: #2980B9;
text-transform: uppercase
}
doc/source/conf.py
+10 -29
View File
@@ -23,35 +23,15 @@ from custom_directives import CustomGalleryItemDirective
# These lines added to enable Sphinx to work without installing Ray.
import mock
MOCK_MODULES = [
"blist",
"gym",
"gym.spaces",
"ray._raylet",
"ray.core.generated",
"ray.core.generated.gcs_pb2",
"ray.core.generated.ray.protocol.Task",
"scipy",
"scipy.signal",
"scipy.stats",
"tensorflow_probability",
"tensorflow",
"tensorflow.contrib",
"tensorflow.contrib.all_reduce",
"tensorflow.contrib.all_reduce.python",
"tensorflow.contrib.layers",
"tensorflow.contrib.rnn",
"tensorflow.contrib.slim",
"tensorflow.core",
"tensorflow.core.util",
"tensorflow.python",
"tensorflow.python.client",
"tensorflow.python.util",
"torch",
"torch.distributed",
"torch.nn",
"torch.nn.parallel",
"torch.utils.data",
"torch.utils.data.distributed"
"blist", "gym", "gym.spaces", "ray._raylet", "ray.core.generated",
"ray.core.generated.gcs_pb2", "ray.core.generated.ray.protocol.Task",
"scipy", "scipy.signal", "scipy.stats", "tensorflow_probability",
"tensorflow", "tensorflow.contrib", "tensorflow.contrib.all_reduce",
"tensorflow.contrib.all_reduce.python", "tensorflow.contrib.layers",
"tensorflow.contrib.rnn", "tensorflow.contrib.slim", "tensorflow.core",
"tensorflow.core.util", "tensorflow.python", "tensorflow.python.client",
"tensorflow.python.util", "torch", "torch.distributed", "torch.nn",
"torch.nn.parallel", "torch.utils.data", "torch.utils.data.distributed"
]
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = mock.Mock()
@@ -394,5 +374,6 @@ def update_context(app, pagename, templatename, context, doctree):
def setup(app):
app.connect('html-page-context', update_context)
app.add_stylesheet('css/custom.css')
# Custom directives
app.add_directive('customgalleryitem', CustomGalleryItemDirective)
doc/source/development.rst
+41 -16
View File
@@ -1,8 +1,8 @@
Development Tips
================
**Note:** Unless otherwise stated, directory and file paths are relative to the
project root directory.
.. note:: Unless otherwise stated, directory and file paths are relative to the project root directory.
Compilation
-----------
@@ -25,9 +25,9 @@ If you run into **Permission Denied** errors when running ``pip install``,
you can try adding ``--user``. You may also need to run something like ``sudo
chown -R $USER $HOME/anaconda3`` (substituting in the appropriate path).
If you make changes to the C++ or Python files, you will need to run the
build so C++ code is recompiled and/or Python files are redeployed in
the ``python`` directory. However, you do not need to rerun
If you make changes to the C++ or Python files, you will need to run the
build so C++ code is recompiled and/or Python files are redeployed in
the ``python`` directory. However, you do not need to rerun
``pip install -e .``. Instead, you can recompile much more quickly by running
the following:
@@ -38,6 +38,31 @@ the following:
This command is not enough to recompile all C++ unit tests. To do so, see
`Testing locally`_.
.. _python-develop:
Developing Ray (Python Only)
----------------------------
.. note:: Unless otherwise stated, directory and file paths are relative to the project root directory.
RLlib, Tune, Autoscaler, and most Python files do not require you to build and compile Ray. Follow these instructions to develop Ray's Python files locally.
1. Pip install the **latest Ray wheels.** See :ref:`install-nightlies` for instructions.
2. Fork and clone the project to your machine. Connect your repository to the upstream (main project) ray repository.
.. code-block:: shell
git clone https://github.com/[your username]/ray.git
cd ray
git remote add upstream https://github.com/ray-project/ray.git
# Make sure you are up-to-date on master.
4. Run ``python python/ray/setup-dev.py``. This sets up links between the ``tune`` dir (among other directories) in your local repo and the one bundled with the ``ray`` package.
.. warning:: Do not run ``pip uninstall ray`` or ``pip install -U`` (for Ray or Ray wheels) if setting up your environment this way. To uninstall or upgrade, you must ``rm -rf`` the installation site (usually a ``site-packages/ray`` location).
Using a local repository for dependencies
-----------------------------------------
@@ -165,7 +190,7 @@ Testing locally
Testing for Python development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Suppose that one of the tests in a file of tests, e.g.,
Suppose that one of the tests in a file of tests, e.g.,
``python/ray/tests/test_basic.py``, is failing. You can run just that
test file locally as follows:
@@ -204,7 +229,7 @@ Alternatively, you can also run one specific C++ test. You can use:
Building the Docs
-----------------
If you make changes that require documentation changes, don't forget to
If you make changes that require documentation changes, don't forget to
update the documentation!
When you make documentation changes, build them locally to verify they render
@@ -213,13 +238,13 @@ correctly. `Sphinx <http://sphinx-doc.org/>`_ is used to generate the documentat
.. code-block:: shell
cd doc
pip install -r requirements-doc.txt
pip install -r requirements-doc.txt
make html
Once done, the docs will be in ``doc/_build/html``. For example, on Mac
OSX, you can open the docs (assuming you are still in the ``doc``
Once done, the docs will be in ``doc/_build/html``. For example, on Mac
OSX, you can open the docs (assuming you are still in the ``doc``
directory) using ``open _build/html/index.html``.
Creating a pull request
-----------------------
@@ -227,7 +252,7 @@ Creating a pull request
To create a pull request (PR) for your change, first go through the
`PR template`_ checklist and ensure you've completed all the steps.
When you push changes to GitHub, the formatting and verification script
When you push changes to GitHub, the formatting and verification script
``ci/travis/format.sh`` is run first. For pushing to your fork, you can
skip this step with ``git push --no-verify``.
@@ -243,7 +268,7 @@ of the following tools. Installation commands are shown for convenience:
**Note:** On MacOS X, don't use HomeBrew to install ``clang-format``, as the only version available is too new.
The Ray project automatically runs continuous integration (CI) tests once a PR
is opened using `Travis-CI <https://travis-ci.com/ray-project/ray/>`_ with
is opened using `Travis-CI <https://travis-ci.com/ray-project/ray/>`_ with
multiple CI test jobs.
@@ -266,7 +291,7 @@ scripts. Some of the examples include:
* ``python python/ray/serve/examples/echo_full.py``
If a Travis-CI build exception doesn't appear to be related to your change,
please visit `this link <https://ray-travis-tracker.herokuapp.com/>`_ to
please visit `this link <https://ray-travis-tracker.herokuapp.com/>`_ to
check recent tests known to be flaky.
@@ -277,11 +302,11 @@ Installation instructions for the tools mentioned here are discussed above in
`Creating a pull request`_.
**Running the linter locally:** To run the Python linter on a specific file, run
``flake8`` as in this example, ``flake8 python/ray/worker.py``.
``flake8`` as in this example, ``flake8 python/ray/worker.py``.
**Autoformatting code**. We use `yapf <https://github.com/google/yapf>`_ for
linting. The config file is ``.style.yapf``. We recommend running
``scripts/yapf.sh`` prior to pushing a PR to format any changed files. Note
``scripts/yapf.sh`` prior to pushing a PR to format any changed files. Note
that some projects, such as dataframes and rllib, are currently excluded.
**Running CI linter:** The Travis CI linter script has multiple components to
doc/source/tune-contrib.rst
+23 -45
View File
@@ -11,48 +11,12 @@ We welcome (and encourage!) all forms of contributions to Tune, including and no
- Test cases to make the codebase more robust.
- Tutorials, blog posts, talks that promote the project.
Developing Tune
---------------
Setting up a development environment
------------------------------------
If you have Ray installed via pip (``pip install -U [link to wheel]`` - you can find the link to the latest wheel `here <https://ray.readthedocs.io/en/latest/installation.html>`__), you can develop Tune locally without needing to compile Ray.
First, you will need your own `fork <https://help.github.com/en/articles/fork-a-repo>`__ to work on the code. Press the Fork button on the `ray project page <https://github.com/ray-project/ray/>`__.
Then, clone the project to your machine and connect your repository to the upstream (main project) ray repository.
.. code-block:: shell
git clone https://github.com/[your username]/ray.git [path to ray directory]
cd [path to ray directory]
git remote add upstream https://github.com/ray-project/ray.git
Before continuing, make sure that your git branch is in sync with the installed Ray binaries (i.e., you are up-to-date on `master <https://github.com/ray-project/ray>`__ and have the latest `wheel <https://ray.readthedocs.io/en/latest/installation.html>`__ installed.)
Then, run `[path to ray directory]/python/ray/setup-dev.py` `(also here on Github) <https://github.com/ray-project/ray/blob/master/python/ray/setup-dev.py>`__ script.
This sets up links between the ``tune`` dir (among other directories) in your local repo and the one bundled with the ``ray`` package.
As a last step make sure to install all packages required for development of tune. This can be done by running:
.. code-block:: shell
pip install -r [path to ray directory]/python/ray/tune/requirements-dev.txt
What can I work on?
-------------------
We use Github to track issues, feature requests, and bugs. Take a look at the
ones labeled `"good first issue" <https://github.com/ray-project/ray/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`__ and `"help wanted" <https://github.com/ray-project/ray/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`__ for a place to start. Look for issues with "[tune]" in the title.
.. note::
If raising a new issue or PR related to Tune, be sure to include "[tune]" in the beginning of the title.
For project organization, Tune maintains a relatively up-to-date organization of
issues on the `Tune Github Project Board <https://github.com/ray-project/ray/projects/4>`__.
Here, you can track and identify how issues are organized.
First, following the instructions in :ref:`python-develop` to develop Tune without compiling Ray.
After Ray is set up, run ``pip install -r ray/python/ray/tune/requirements-dev.txt`` to install all packages required for Tune development.
Submitting and Merging a Contribution
-------------------------------------
@@ -65,12 +29,12 @@ There are a couple steps to merge a contribution.
git remote add upstream https://github.com/ray-project/ray.git
git fetch upstream
git rebase upstream/master
git rebase upstream/master # or git pull . upstream/master
2. Make sure all existing tests `pass <tune-contrib.html#testing>`__.
3. If introducing a new feature or patching a bug, be sure to add new test cases
in the relevant file in `tune/tests/`.
4. Document the code. Public functions need to be documented, and remember to provide an usage
in the relevant file in ``tune/tests/``.
4. Document the code. Public functions need to be documented, and remember to provide a usage
example if applicable.
5. Request code reviews from other contributors and address their comments. One fast way to get reviews is
to help review others' code so that they return the favor. You should aim to improve the code as much as
@@ -93,14 +57,28 @@ burden and speedup review process.
Documentation should be documented in `Google style <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__ format.
We also have tests for code formatting and linting that need to pass before merge.
Install `yapf==0.23, flake8, flake8-quotes` (these are also in the `requirements-dev.txt` found in ``python/ray/tune``). You can run the following locally:
We also have tests for code formatting and linting that need to pass before merge. You can run the following locally:
.. code-block:: shell
ray/scripts/format.sh
What can I work on?
-------------------
We use Github to track issues, feature requests, and bugs. Take a look at the
ones labeled `"good first issue" <https://github.com/ray-project/ray/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`__ and `"help wanted" <https://github.com/ray-project/ray/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`__ for a place to start. Look for issues with "[tune]" in the title.
.. note::
If raising a new issue or PR related to Tune, be sure to include "[tune]" in the title and add a ``tune`` label.
For project organization, Tune maintains a relatively up-to-date organization of
issues on the `Tune Github Project Board <https://github.com/ray-project/ray/projects/4>`__.
Here, you can track and identify how issues are organized.
Becoming a Reviewer
-------------------
doc/source/tune-package-ref.rst
+274 -26
View File
@@ -1,54 +1,302 @@
Tune Package Reference
=======================
ray.tune
--------
Training (tune.run, tune.Experiment)
------------------------------------
.. automodule:: ray.tune
:members:
:show-inheritance:
:exclude-members: TuneError, Trainable, DurableTrainable
tune.run
~~~~~~~~
.. autofunction:: ray.tune.run
tune.run_experiments
~~~~~~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.run_experiments
tune.Experiment
~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.Experiment
Trainable (tune.Trainable, tune.track)
--------------------------------------
tune.Trainable
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.Trainable
:members:
:member-order: groupwise
:private-members:
:members:
tune.DurableTrainable
~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.DurableTrainable
tune.track
~~~~~~~~~~
.. automodule:: ray.tune.track
:members:
:exclude-members: init, shutdown
StatusReporter
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.function_runner.StatusReporter
:members: __call__, logdir
ray.tune.schedulers
-------------------
Sampling (tune.rand, tune.grid_search...)
-----------------------------------------
.. automodule:: ray.tune.schedulers
:members:
tune.randn
~~~~~~~~~~
.. autofunction:: ray.tune.randn
tune.loguniform
~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.loguniform
tune.uniform
~~~~~~~~~~~~
.. autofunction:: ray.tune.uniform
tune.choice
~~~~~~~~~~~
.. autofunction:: ray.tune.choice
tune.sample_from
~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.sample_from
tune.grid_search
~~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.grid_search
Stopper (tune.Stopper)
----------------------
.. autoclass:: ray.tune.Stopper
:members: __call__, stop_all
Analysis (tune.analysis)
------------------------
ExperimentAnalysis
~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.ExperimentAnalysis
:show-inheritance:
ray.tune.suggest
----------------
.. automodule:: ray.tune.suggest
:members:
:exclude-members: function, sample_from, grid_search, SuggestionAlgorithm
:show-inheritance:
Analysis
~~~~~~~~
.. autoclass:: ray.tune.Analysis
:members:
Schedulers (tune.schedulers)
----------------------------
FIFOScheduler
~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.FIFOScheduler
HyperBandScheduler
~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.HyperBandScheduler
ASHAScheduler/AsyncHyperBandScheduler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.AsyncHyperBandScheduler
.. autoclass:: ray.tune.schedulers.ASHAScheduler
MedianStoppingRule
~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.MedianStoppingRule
PopulationBasedTraining
~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.PopulationBasedTraining
TrialScheduler
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.TrialScheduler
:members:
Search Algorithms (tune.suggest)
--------------------------------
BasicVariantGenerator
~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.BasicVariantGenerator
AxSearch
~~~~~~~~
.. autoclass:: ray.tune.suggest.ax.AxSearch
BayesOptSearch
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.bayesopt.BayesOptSearch
TuneBOHB
~~~~~~~~
.. autoclass:: ray.tune.suggest.bohb.TuneBOHB
DragonflySearch
~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.dragonfly.DragonflySearch
HyperOptSearch
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.hyperopt.HyperOptSearch
NevergradSearch
~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.nevergrad.NevergradSearch
SigOptSearch
~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.sigopt.SigOptSearch
SkOptSearch
~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.skopt.SkOptSearch
SearchAlgorithm
~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.SearchAlgorithm
:members:
SuggestionAlgorithm
~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.SuggestionAlgorithm
:members:
:private-members:
:show-inheritance:
Repeater
~~~~~~~~
.. autoclass:: ray.tune.suggest.Repeater
ray.tune.track
--------------
Loggers (tune.logger)
---------------------
.. automodule:: ray.tune.track
:members:
ray.tune.logger
---------------
Logger
~~~~~~
.. autoclass:: ray.tune.logger.Logger
UnifiedLogger
~~~~~~~~~~~~~
.. autoclass:: ray.tune.logger.UnifiedLogger
TBXLogger
~~~~~~~~~
.. autoclass:: ray.tune.logger.TBXLogger
JsonLogger
~~~~~~~~~~
.. autoclass:: ray.tune.logger.JsonLogger
CSVLogger
~~~~~~~~~
.. autoclass:: ray.tune.logger.CSVLogger
MLFLowLogger
~~~~~~~~~~~~
.. autoclass:: ray.tune.logger.MLFLowLogger
Reporters
---------
ProgressReporter
~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.ProgressReporter
:members:
CLIReporter
~~~~~~~~~~~
.. autoclass:: ray.tune.CLIReporter
JupyterNotebookReporter
~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.JupyterNotebookReporter
Internals
---------
Registry
~~~~~~~~
.. autofunction:: ray.tune.register_trainable
.. autofunction:: ray.tune.register_env
RayTrialExecutor
~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.ray_trial_executor.RayTrialExecutor
:members:
TrialExecutor
~~~~~~~~~~~~~
.. autoclass:: ray.tune.trial_executor.TrialExecutor
:members:
TrialRunner
~~~~~~~~~~~
.. autoclass:: ray.tune.trial_runner.TrialRunner
Trial
~~~~~
.. autoclass:: ray.tune.trial.Trial
Resources
~~~~~~~~~
.. autoclass:: ray.tune.resources.Resources