Merge pull request #524 from JoelPasvolsky/warnings

Remove ambiguous xrefs to reduce build warnings

docs/reference/composites.rst

@@ -149,6 +149,7 @@ FixedEmbeddingComposite
 -----------------------
 
 .. autoclass:: FixedEmbeddingComposite
+   :show-inheritance:
 
 Properties
 ~~~~~~~~~~

docs/reference/samplers.rst

@@ -29,6 +29,7 @@ DWaveSampler
 ============
 
 .. autoclass:: DWaveSampler
+   :show-inheritance: 
 
 Properties
 ----------

docs/reference/warnings.rst

@@ -5,7 +5,7 @@ Warnings
 ========
 
 Settings for raising warnings may be configured by tools such as composites or
-:doc:`docs_inspector/sdk_index`.
+:doc:`oceandocs:docs_inspector/sdk_index`.
 
 This example configures warnings for an instance of the
 :class:`~dwave.system.composites.EmbeddingComposite()` class used on a sampler

dwave/embedding/transforms.py

@@ -548,7 +548,7 @@ def unembed_sampleset(target_sampleset, embedding, source_bqm,
             already exists in the sample set then it is overwritten.
 
     Returns:
-        :obj:`.SampleSet`: Sample set in the source BQM.
+        :obj:`~dimod.SampleSet`: Sample set in the source BQM.
 
     Examples:
        This example unembeds from a square target graph samples of a triangular

dwave/system/composites/cutoffcomposite.py

@@ -26,7 +26,7 @@
 
 
 class CutOffComposite(dimod.ComposedSampler):
-    """Composite to remove interactions below a specified cutoff value.
+    r"""Composite to remove interactions below a specified cutoff value.
 
     Prunes the binary quadratic model (BQM) submitted to the child sampler by
     retaining only interactions with values commensurate with the sampler's
@@ -89,7 +89,7 @@ def children(self):
     @property
     def parameters(self):
         """A dict where keys are the keyword parameters accepted by the sampler methods
-        and values are lists of the properties relevent to each parameter."""
+        and values are lists of the properties relevant to each parameter."""
         return self.child.parameters.copy()
 
     @property
@@ -108,14 +108,14 @@ def sample(self, bqm, **parameters):
         that minimize the original BQM's energy for the returned samples.
 
         Args:
-            bqm (:obj:`dimod.BinaryQuadraticModel`):
+            bqm (:obj:`~dimod.BinaryQuadraticModel`):
                 Binary quadratic model to be sampled from.
 
             **parameters:
                 Parameters for the sampling method, specified by the child sampler.
 
         Returns:
-            :obj:`dimod.SampleSet`
+            :obj:`~dimod.SampleSet`
 
         Examples:
             See the example in :class:`CutOffComposite`.
@@ -285,7 +285,7 @@ def sample_poly(self, poly, **kwargs):
                 Parameters for the sampling method, specified by the child sampler.
 
         Returns:
-            :obj:`dimod.SampleSet`
+            :obj:`~dimod.SampleSet`
 
         Examples:
             See the example in :class:`PolyCutOffComposite`.

dwave/system/composites/embedding.py

@@ -48,12 +48,12 @@ class EmbeddingComposite(dimod.ComposedSampler):
     """Maps problems to a structured sampler.
 
     Automatically minor-embeds a problem into a structured sampler such as a
-    D-Wave system. A new minor-embedding is calculated each time one of its
-    sampling methods is called.
+    D-Wave quantum computer. A new minor-embedding is calculated each time one 
+    of its sampling methods is called.
 
     Args:
         child_sampler (:class:`dimod.Sampler`):
-            A dimod sampler, such as a :obj:`.DWaveSampler`, that accepts
+            A dimod sampler, such as a :obj:`DWaveSampler`, that accepts
             only binary quadratic models of a particular structure.
 
         find_embedding (function, optional):
@@ -66,12 +66,12 @@ class EmbeddingComposite(dimod.ComposedSampler):
             keyword arguments.
 
         scale_aware (bool, optional, default=False):
-            Pass chain interactions to child samplers that accept an `ignored_interactions`
-            parameter.
+            Pass chain interactions to child samplers that accept an 
+            ``ignored_interactions`` parameter.
 
         child_structure_search (function, optional):
-            A function `child_structure_search(sampler)` that accepts a sampler
-            and returns the :attr:`dimod.Structured.structure`.
+            A function that accepts a sampler and returns the 
+            :attr:`~dimod.Structured.structure` attribute.
             Defaults to :func:`dimod.child_structure_dfs`.
 
     Examples:
@@ -138,12 +138,17 @@ def __init__(self, child_sampler,
     """
 
     return_embedding_default = False
-    """Defines the default behaviour for :meth:`.sample`'s `return_embedding`
-    kwarg.
+    """Defines the default behavior for returning embeddings. 
+    
+    Sets the default for the :meth:`.sample` method's 
+    ``return_embedding`` optional parameter (``kwarg``).
     """
 
     warnings_default = WarningAction.IGNORE
-    """Defines the default behavior for :meth:`.sample`'s `warnings` kwarg.
+    """Defines the default behavior for warnings. 
+    
+    Sets the default for the :meth:`.sample` method's 
+    ``warnings`` optional parameter (``kwarg``).
     """
 
     def sample(self, bqm, chain_strength=None,
@@ -156,56 +161,56 @@ def sample(self, bqm, chain_strength=None,
         """Sample from the provided binary quadratic model.
 
         Args:
-            bqm (:obj:`dimod.BinaryQuadraticModel`):
+            bqm (:obj:`~dimod.BinaryQuadraticModel`):
                 Binary quadratic model to be sampled from.
 
             chain_strength (float/mapping/callable, optional):
                 Sets the coupling strength between qubits representing variables 
                 that form a :term:`chain`. Mappings should specify the required 
                 chain strength for each variable. Callables should accept the BQM 
                 and embedding and return a float or mapping. By default, 
-                `chain_strength` is calculated with
+                ``chain_strength`` is calculated with
                 :func:`~dwave.embedding.chain_strength.uniform_torque_compensation`.
 
             chain_break_method (function/list, optional):
                 Method or methods used to resolve chain breaks. If multiple
                 methods are given, the results are concatenated and a new field
-                called "chain_break_method" specifying the index of the method
+                called ``chain_break_method`` specifying the index of the method
                 is appended to the sample set.
                 See :func:`~dwave.embedding.unembed_sampleset` and
-                :mod:`dwave.embedding.chain_breaks`.
+                :mod:`~dwave.embedding.chain_breaks`.
 
             chain_break_fraction (bool, optional, default=True):
-                Add a `chain_break_fraction` field to the unembedded response with
-                the fraction of chains broken before unembedding.
+                Add a ``chain_break_fraction`` field to the unembedded response 
+                with the fraction of chains broken before unembedding.
 
             embedding_parameters (dict, optional):
                 If provided, parameters are passed to the embedding method as
-                keyword arguments. Overrides any `embedding_parameters` passed
+                keyword arguments. Overrides any embedding parameters passed
                 to the constructor.
 
             return_embedding (bool, optional):
                 If True, the embedding, chain strength, chain break method and
-                embedding parameters are added to :attr:`dimod.SampleSet.info`
-                of the returned sample set. The default behaviour is defined
-                by :attr:`return_embedding_default`, which itself defaults to
-                False.
+                embedding parameters are added to the :attr:`~dimod.SampleSet.info`
+                field of the returned sample set. The default behavior is defined
+                by the :attr:`return_embedding_default` attribute, which by default 
+                is False.
 
             warnings (:class:`~dwave.system.warnings.WarningAction`, optional):
-                Defines what warning action to take, if any. See
-                :mod:`~dwave.system.warnings`. The default behaviour is defined
-                by :attr:`warnings_default`, which itself defaults to
+                Defines what warning action to take, if any (see the
+                :ref:`warnings_system` section). The default behavior is defined
+                by the :attr:`warnings_default` attribute, which by default is
                 :class:`~dwave.system.warnings.IGNORE`
 
             **parameters:
                 Parameters for the sampling method, specified by the child
                 sampler.
 
         Returns:
-            :obj:`dimod.SampleSet`
+            :obj:`~dimod.SampleSet`
 
         Examples:
-            See the example in :class:`EmbeddingComposite`.
+            See the example in :class:`.EmbeddingComposite`.
 
         """
         if return_embedding is None:
@@ -318,7 +323,7 @@ class LazyFixedEmbeddingComposite(EmbeddingComposite, dimod.Structured):
             Structured dimod sampler.
 
         find_embedding (function, default=:func:`minorminer.find_embedding`):
-            A function `find_embedding(S, T, **kwargs)` where `S` and `T`
+            A function ``find_embedding(S, T, **kwargs)`` where ``S`` and ``T``
             are edgelists. The function can accept additional keyword arguments.
             The function is used to find the embedding for the first problem
             solved.
@@ -339,7 +344,7 @@ class LazyFixedEmbeddingComposite(EmbeddingComposite, dimod.Structured):
         ['a', 'b']
 
     """
-
+        
     @property
     def nodelist(self):
         """list: Nodes available to the composed sampler."""
@@ -442,36 +447,36 @@ def sample(self, bqm, **parameters):
         sampling methods reuse this embedding.
 
         Args:
-            bqm (:obj:`dimod.BinaryQuadraticModel`):
+            bqm (:obj:`~dimod.BinaryQuadraticModel`):
                 Binary quadratic model to be sampled from.
 
             chain_strength (float/mapping/callable, optional):
                 Sets the coupling strength between qubits representing variables 
                 that form a :term:`chain`. Mappings should specify the required 
                 chain strength for each variable. Callables should accept the BQM 
                 and embedding and return a float or mapping. By default, 
-                `chain_strength` is calculated with
+                ``chain_strength`` is calculated with
                 :func:`~dwave.embedding.chain_strength.uniform_torque_compensation`.
 
             chain_break_method (function, optional):
                 Method used to resolve chain breaks during sample unembedding.
                 See :func:`~dwave.embedding.unembed_sampleset`.
 
             chain_break_fraction (bool, optional, default=True):
-                Add a ‘chain_break_fraction’ field to the unembedded response with
+                Add a ``chain_break_fraction`` field to the unembedded response with
                 the fraction of chains broken before unembedding.
 
             embedding_parameters (dict, optional):
                 If provided, parameters are passed to the embedding method as
-                keyword arguments. Overrides any `embedding_parameters` passed
+                keyword arguments. Overrides any embedding parameters passed
                 to the constructor. Only used on the first call.
 
             **parameters:
                 Parameters for the sampling method, specified by the child
                 sampler.
 
         Returns:
-            :obj:`dimod.SampleSet`
+            :obj:`~dimod.SampleSet`
 
         """
         if self.embedding is None:
@@ -504,15 +509,15 @@ class FixedEmbeddingComposite(LazyFixedEmbeddingComposite):
 
     Args:
         child_sampler (dimod.Sampler):
-            Structured dimod sampler such as a D-Wave system.
+            Structured dimod sampler such as a D-Wave quantum computer.
 
         embedding (dict[hashable, iterable], optional):
-            Mapping from a source graph to the specified sampler’s graph (the
+            Mapping from a source graph to the specified sampler's graph (the
             target graph).
 
         source_adjacency (dict[hashable, iterable]):
-            Deprecated. Dictionary to describe source graph as `{node:
-            {node neighbours}}`.
+            Deprecated. Dictionary to describe source graph as ``{node:
+            {node neighbours}}``.
 
         kwargs:
             See the :class:`EmbeddingComposite` class for additional keyword
@@ -579,15 +584,16 @@ class AutoEmbeddingComposite(EmbeddingComposite):
 
     This composite first tries to submit the binary quadratic model directly
     to the child sampler and only embeds if a
-    :exc:`dimod.exceptions.BinaryQuadraticModelStructureError` is raised.
+    :exc:`~dimod.exceptions.BinaryQuadraticModelStructureError` exception is 
+    raised.
 
     Args:
         child_sampler (:class:`dimod.Sampler`):
             Structured dimod sampler, such as a
             :obj:`~dwave.system.samplers.DWaveSampler()`.
 
         find_embedding (function, optional):
-            A function `find_embedding(S, T, **kwargs)` where `S` and `T`
+            A function ``find_embedding(S, T, **kwargs)`` where ``S`` and ``T``
             are edgelists. The function can accept additional keyword arguments.
             Defaults to :func:`minorminer.find_embedding`.
 

dwave/system/composites/reversecomposite.py

@@ -25,8 +25,7 @@
 
 
 class ReverseAdvanceComposite(dimod.ComposedSampler):
-    """
-    Composite that reverse anneals an initial sample through a sequence of anneal
+    r"""Composite that reverse anneals an initial sample through a sequence of anneal
     schedules.
 
     If you do not specify an initial sample, a random sample is used for the first
@@ -43,7 +42,7 @@ class ReverseAdvanceComposite(dimod.ComposedSampler):
        This example runs 100 reverse anneals each for three schedules on a problem
        constructed by setting random :math:`\pm 1` values on a clique (complete
        graph) of 15 nodes, minor-embedded on a D-Wave system using the
-       :class:`.DWaveCliqueSampler` sampler.
+       :class:`DWaveCliqueSampler` sampler.
 
        >>> import dimod
        >>> from dwave.system import DWaveCliqueSampler, ReverseAdvanceComposite
@@ -80,11 +79,11 @@ def properties(self):
         return {'child_properties': self.child.properties.copy()}
 
     def sample(self, bqm, anneal_schedules=None, **parameters):
-        """Sample the binary quadratic model using reverse annealing along a given set 
+        r"""Sample the binary quadratic model using reverse annealing along a given set 
         of anneal schedules.
 
         Args:
-            bqm (:obj:`dimod.BinaryQuadraticModel`):
+            bqm (:obj:`~dimod.BinaryQuadraticModel`):
                 Binary quadratic model to be sampled from.
 
             anneal_schedules (list of lists, optional, default=[[[0, 1], [1, 0.35], [9, 0.35], [10, 1]]]): 
@@ -100,7 +99,8 @@ def sample(self, bqm, anneal_schedules=None, **parameters):
                 Parameters for the sampling method, specified by the child sampler.
 
         Returns:
-            :obj:`dimod.SampleSet` that has initial_state and schedule_index fields.
+            :obj:`~dimod.SampleSet` that has ``initial_state`` and ``schedule_index`` 
+            fields.
 
         Examples:
            This example runs 100 reverse anneals each for three schedules on a problem
@@ -194,18 +194,19 @@ def sample(self, bqm, anneal_schedules=None, **parameters):
 
 
 class ReverseBatchStatesComposite(dimod.ComposedSampler, dimod.Initialized):
-    r"""Composite that reverse anneals from multiple initial samples. Each submission is independent
-    from one another.
+    r"""Composite that reverse anneals from multiple initial samples. 
+    
+    Each submission is independent from one another.
 
     Args:
-       sampler (:obj:`dimod.Sampler`):
+       sampler (:obj:`~dimod.Sampler`):
             A dimod sampler.
 
     Examples:
        This example runs three reverse anneals from two configured and one 
        randomly generated initial states on a problem constructed by setting 
        random :math:`\pm 1` values on a clique (complete graph) of 15 nodes, 
-       minor-embedded on a D-Wave system using the :class:`.DWaveCliqueSampler` 
+       minor-embedded on a D-Wave system using the :class:`DWaveCliqueSampler` 
        sampler. 
 
        >>> import dimod
@@ -247,7 +248,7 @@ def sample(self, bqm, initial_states=None, initial_states_generator='random', nu
         r"""Sample the binary quadratic model using reverse annealing from multiple initial states.
 
         Args:
-            bqm (:obj:`dimod.BinaryQuadraticModel`):
+            bqm (:obj:`~dimod.BinaryQuadraticModel`):
                 Binary quadratic model to be sampled from.
 
             initial_states (samples-like, optional, default=None):
@@ -287,13 +288,13 @@ def sample(self, bqm, initial_states=None, initial_states_generator='random', nu
                 Parameters for the sampling method, specified by the child sampler.
 
         Returns:
-            :obj:`dimod.SampleSet` that has initial_state field.
+            :obj:`~dimod.SampleSet` that has an ``initial_state`` field.
 
         Examples:
            This example runs three reverse anneals from two configured and one 
            randomly generated initial states on a problem constructed by setting
            random :math:`\pm 1` values on a clique (complete graph) of 15 nodes, 
-           minor-embedded on a D-Wave system using the :class:`.DWaveCliqueSampler` 
+           minor-embedded on a D-Wave system using the :class:`DWaveCliqueSampler` 
            sampler.
            
            >>> import dimod