From b1cddb7814c334e5e05945d67c8da7c6366a9398 Mon Sep 17 00:00:00 2001 From: Bryon Tjanaka <38124174+btjanaka@users.noreply.github.com> Date: Thu, 5 Oct 2023 14:04:38 -0700 Subject: [PATCH] Fix broken cross-refs in docs (#393) ## Description Fixed a couple of broken links that reference other objects in the documentation, particularly related to rankers. Also changed the name of several private constants in the rankers docs to make pylint happy. ## TODO ## Questions ## Status - [x] I have read the guidelines in [CONTRIBUTING.md](https://github.com/icaros-usc/pyribs/blob/master/CONTRIBUTING.md) - [x] I have formatted my code using `yapf` - [x] I have tested my code by running `pytest` - [x] I have linted my code with `pylint` - [x] I have added a one-line description of my change to the changelog in `HISTORY.md` - [x] This PR is ready to go --- HISTORY.md | 1 + ribs/emitters/_evolution_strategy_emitter.py | 24 +++++----- .../_gradient_arborescence_emitter.py | 28 ++++++------ ribs/emitters/rankers.py | 45 ++++++++++--------- 4 files changed, 52 insertions(+), 46 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index f060bf709..e5b2f84f6 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -12,6 +12,7 @@ - Test pyribs installation in tutorials ({pr}`384`) - Add cron job for testing installation ({pr}`389`) +- Fix broken cross-refs in docs ({pr}`393`) ## 0.6.3 diff --git a/ribs/emitters/_evolution_strategy_emitter.py b/ribs/emitters/_evolution_strategy_emitter.py index 94abee146..913179cfd 100644 --- a/ribs/emitters/_evolution_strategy_emitter.py +++ b/ribs/emitters/_evolution_strategy_emitter.py @@ -23,18 +23,20 @@ class EvolutionStrategyEmitter(EmitterBase): x0 (np.ndarray): Initial solution. Must be 1-dimensional. sigma0 (float): Initial step size / standard deviation of the distribution from which solutions are sampled. - ranker (Callable or str): The ranker is a :class:`RankerBase` object - that orders the solutions after they have been evaluated in the - environment. This parameter may be a callable (e.g. a class or - a lambda function) that takes in no parameters and returns an - instance of :class:`RankerBase`, or it may be a full or abbreviated - ranker name as described in - :meth:`ribs.emitters.rankers.get_ranker`. + ranker (Callable or str): The ranker is a + :class:`~ribs.emitters.rankers.RankerBase` object that orders the + solutions after they have been evaluated in the environment. This + parameter may be a callable (e.g. a class or a lambda function) that + takes in no parameters and returns an instance of + :class:`~ribs.emitters.rankers.RankerBase`, or it may be a full or + abbreviated ranker name as described in + :mod:`ribs.emitters.rankers`. es (Callable or str): The evolution strategy is an - :class:`EvolutionStrategyBase` object that is used to adapt the - distribution from which new solutions are sampled. This parameter - may be a callable (e.g. a class or a lambda function) that takes in - the parameters of :class:`EvolutionStrategyBase` along with kwargs + :class:`~ribs.emitters.opt.EvolutionStrategyBase` object that is + used to adapt the distribution from which new solutions are sampled. + This parameter may be a callable (e.g. a class or a lambda function) + that takes in the parameters of + :class:`~ribs.emitters.opt.EvolutionStrategyBase` along with kwargs provided by the ``es_kwargs`` argument, or it may be a full or abbreviated optimizer name as described in :mod:`ribs.emitters.opt`. es_kwargs (dict): Additional arguments to pass to the evolution diff --git a/ribs/emitters/_gradient_arborescence_emitter.py b/ribs/emitters/_gradient_arborescence_emitter.py index efcfa72f7..4baf3b82b 100644 --- a/ribs/emitters/_gradient_arborescence_emitter.py +++ b/ribs/emitters/_gradient_arborescence_emitter.py @@ -59,12 +59,14 @@ class GradientArborescenceEmitter(EmitterBase): sigma0 (float): Initial step size / standard deviation of the distribution of gradient coefficients. lr (float): Learning rate for the gradient optimizer. - ranker (Callable or str): The ranker is a :class:`RankerBase` object - that orders the solutions after they have been evaluated in the - environment. This parameter may be a callable (e.g. a class or a - lambda function) that takes in no parameters and returns an instance - of :class:`RankerBase`, or it may be a full or abbreviated ranker - name as described in :mod:`ribs.emitters.rankers`. + ranker (Callable or str): The ranker is a + :class:`~ribs.emitters.rankers.RankerBase` object that orders the + solutions after they have been evaluated in the environment. This + parameter may be a callable (e.g. a class or a lambda function) that + takes in no parameters and returns an instance of + :class:`~ribs.emitters.rankers.RankerBase`, or it may be a full or + abbreviated ranker name as described in + :mod:`ribs.emitters.rankers`. selection_rule ("mu" or "filter"): Method for selecting parents in CMA-ES. With "mu" selection, the first half of the solutions will be selected as parents, while in "filter", any solutions that were @@ -87,13 +89,13 @@ class GradientArborescenceEmitter(EmitterBase): :mod:`ribs.emitters.opt` for the arguments allowed by each optimizer. Note that we already pass in ``theta0`` and ``lr``. es (Callable or str): The evolution strategy is an - :class:`EvolutionStrategyBase` object that is used to adapt the - distribution from which new gradient coefficients are sampled. This - parameter may be a callable (e.g. a class or a lambda function) that - takes in the parameters of :class:`EvolutionStrategyBase` along with - kwargs provided by the ``es_kwargs`` argument, or it may be a full - or abbreviated optimizer name as described in - :mod:`ribs.emitters.opt`. + :class:`~ribs.emitters.opt.EvolutionStrategyBase` object that is + used to adapt the distribution from which new solutions are sampled. + This parameter may be a callable (e.g. a class or a lambda function) + that takes in the parameters of + :class:`~ribs.emitters.opt.EvolutionStrategyBase` along with kwargs + provided by the ``es_kwargs`` argument, or it may be a full or + abbreviated optimizer name as described in :mod:`ribs.emitters.opt`. es_kwargs (dict): Additional arguments to pass to the evolution strategy optimizer. See the evolution-strategy-based optimizers in :mod:`ribs.emitters.opt` for the arguments allowed by each diff --git a/ribs/emitters/rankers.py b/ribs/emitters/rankers.py index f7399cc6d..f3a7b2b94 100644 --- a/ribs/emitters/rankers.py +++ b/ribs/emitters/rankers.py @@ -2,9 +2,10 @@ The rankers implemented in this file are intended to be used with emitters. Specifically, a ranker object should be initialized or passed in the emitters. -The ``Ranker`` object will define the :meth:`rank` method which returns the -result of a descending argsort of the solutions. It will also define a -:meth:`reset` method which resets the internal state of the object. +The ``Ranker`` object will define the :meth:`~RankerBase.rank` method which +returns the result of a descending argsort of the solutions. It will also define +a :meth:`~RankerBase.reset` method which resets the internal state of the +object. When specifying which ranker to use for each emitter, one could either pass in the full name of a ranker, e.g. "ImprovementRanker", or the abbreviated name of @@ -46,21 +47,21 @@ ] # Define common docstrings -_args = DocstringComponents(core_args) +_ARGS = DocstringComponents(core_args) -_rank_args = f""" +_RANK_ARGS = f""" Args: emitter (ribs.emitters.EmitterBase): Emitter that this ``ranker`` object belongs to. archive (ribs.archives.ArchiveBase): Archive used by ``emitter`` when creating and inserting solutions. rng (numpy.random.Generator): A random number generator. -{_args.solution_batch} -{_args.objective_batch} -{_args.measures_batch} -{_args.status_batch} -{_args.value_batch} -{_args.metadata_batch} +{_ARGS.solution_batch} +{_ARGS.objective_batch} +{_ARGS.measures_batch} +{_ARGS.status_batch} +{_ARGS.value_batch} +{_ARGS.metadata_batch} Returns: tuple(numpy.ndarray, numpy.ndarray): the first array (shape @@ -71,7 +72,7 @@ the number of values that the rank function used. """ -_reset_args = """ +_RESET_ARGS = """ Args: emitter (ribs.emitters.EmitterBase): Emitter that this ``ranker`` object belongs to. @@ -87,7 +88,7 @@ class RankerBase(ABC): Every ranker has a :meth:`rank` method that returns a list of indices that indicate how the solutions should be ranked and a :meth:`reset` method that resets the internal state of the ranker - (e.g. in :class:`ribs.emitters.rankers._random_direction_ranker`). + (e.g. in :class:`~ribs.emitters.rankers.RandomDirectionRanker`). Child classes are only required to override :meth:`rank`. """ @@ -102,7 +103,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, rank.__doc__ = f""" Generates a batch of indices that represents an ordering of ``solution_batch``. -{_rank_args} +{_RANK_ARGS} """ def reset(self, emitter, archive, rng): @@ -112,7 +113,7 @@ def reset(self, emitter, archive, rng): reset.__doc__ = f""" Resets the internal state of the ranker. -{_reset_args} +{_RESET_ARGS} """ @@ -139,7 +140,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, rank.__doc__ = f""" Generates a list of indices that represents an ordering of solutions. -{_rank_args} +{_RANK_ARGS} """ @@ -179,7 +180,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, rank.__doc__ = f""" Generates a list of indices that represents an ordering of solutions. -{_rank_args} +{_RANK_ARGS} """ @@ -222,7 +223,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, rank.__doc__ = f""" Ranks the solutions based on projection onto a direction in the archive. -{_rank_args} +{_RANK_ARGS} """ def reset(self, emitter, archive, rng): @@ -240,7 +241,7 @@ def reset(self, emitter, archive, rng): direction is then scaled to the archive bounds so that it is a random archive direction. -{_reset_args} +{_RESET_ARGS} """ @@ -288,7 +289,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, Ranks the solutions first by whether they are added, then by their projection onto a random direction in the archive. -{_rank_args} +{_RANK_ARGS} """ def reset(self, emitter, archive, rng): @@ -316,7 +317,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, rank.__doc__ = f""" Ranks the solutions based on their objective values. -{_rank_args} +{_RANK_ARGS} """ @@ -345,7 +346,7 @@ def rank(self, emitter, archive, rng, solution_batch, objective_batch, Ranks the solutions based on their objective values, while prioritizing newly added solutions. -{_rank_args} +{_RANK_ARGS} """