Add proper cross-references in docs.

.gitignore

@@ -32,3 +32,6 @@ __pycache__/
 /dataset_db.pyon
 /device_db*.py
 /test*
+
+# Pycharm/Jetbrains Development
+.idea/

artiq/coredevice/ad9914.py

@@ -162,16 +162,16 @@ def init_sync(self, sync_delay):
     def set_phase_mode(self, phase_mode):
         """Sets the phase mode of the DDS channel. Supported phase modes are:
 
-        * ``PHASE_MODE_CONTINUOUS``: the phase accumulator is unchanged when
+        * :const:`PHASE_MODE_CONTINUOUS`: the phase accumulator is unchanged when
           switching frequencies. The DDS phase is the sum of the phase
           accumulator and the phase offset. The only discrete jumps in the
           DDS output phase come from changes to the phase offset.
 
-        * ``PHASE_MODE_ABSOLUTE``: the phase accumulator is reset when
+        * :const:`PHASE_MODE_ABSOLUTE`: the phase accumulator is reset when
           switching frequencies. Thus, the phase of the DDS at the time of
           the frequency change is equal to the phase offset.
 
-        * ``PHASE_MODE_TRACKING``: when switching frequencies, the phase
+        * :const:`PHASE_MODE_TRACKING`: when switching frequencies, the phase
           accumulator is set to the value it would have if the DDS had been
           running at the specified frequency since the start of the
           experiment.
@@ -193,7 +193,7 @@ def set_mu(self, ftw, pow=0, phase_mode=_PHASE_MODE_DEFAULT,
         :param ftw: frequency to generate.
         :param pow: adds an offset to the phase.
         :param phase_mode: if specified, overrides the default phase mode set
-            by ``set_phase_mode`` for this call.
+            by :meth:`set_phase_mode` for this call.
         :param ref_time: reference time used to compute phase. Specifying this
             makes it easier to have a well-defined phase relationship between
             DDSes on the same bus that are updated at a similar time. 
@@ -270,7 +270,7 @@ def asf_to_amplitude(self, asf):
     @kernel
     def set(self, frequency, phase=0.0, phase_mode=_PHASE_MODE_DEFAULT,
             amplitude=1.0):
-        """Like ``set_mu``, but uses Hz and turns."""
+        """Like :meth:`set_mu`, but uses Hz and turns."""
         self.set_mu(self.frequency_to_ftw(frequency),
                     self.turns_to_pow(phase), phase_mode,
                     self.amplitude_to_asf(amplitude))
@@ -323,7 +323,7 @@ def xftw_to_frequency(self, xftw):
 
     @kernel
     def set_x(self, frequency, amplitude=1.0):
-        """Like ``set_x_mu``, but uses Hz and turns.
+        """Like :meth:`set_x_mu`, but uses Hz and turns.
 
         Note that the precision of ``float`` is less than the precision
         of the extended frequency tuning word.

artiq/coredevice/dma.py

@@ -34,7 +34,7 @@ def dma_playback(timestamp: TInt64, ptr: TInt32) -> TNone:
 
 
 class DMARecordContextManager:
-    """Context manager returned by ``CoreDMA.record()``.
+    """Context manager returned by :meth:`CoreDMA.record()`.
 
     Upon entering, starts recording a DMA trace. All RTIO operations are
     redirected to a newly created DMA buffer after this call, and ``now``

artiq/coredevice/spi2.py

@@ -184,7 +184,7 @@ def update_xfer_duration_mu(self, div, length):
         experiments and are known.
 
         This method is portable and can also be called from e.g.
-        ``__init__``.
+        :meth:`__init__`.
 
         :param div: SPI clock divider (see: :meth:`set_config_mu`)
         :param length: SPI transfer length (see: :meth:`set_config_mu`)

artiq/coredevice/suservo.py

@@ -253,7 +253,7 @@ def set(self, en_out, en_iir=0, profile=0):
         This method does not advance the timeline. Output RF switch setting
         takes effect immediately and is independent of any other activity
         (profile settings, other channels). The RF switch behaves like
-        ``TTLOut``. RTIO event replacement is supported. IIR updates take place
+        :class:`artiq.coredevice.ttl.TTLOut`. RTIO event replacement is supported. IIR updates take place
         once the RF switch has been enabled for the configured delay and the
         profile setting has been stable. Profile changes take between one and
         two servo cycles to reach the DDS.

artiq/coredevice/ttl.py

@@ -2,8 +2,8 @@
 Drivers for TTL signals on RTIO.
 
 TTL channels (including the clock generator) all support output event
-replacement. For example, pulses of "zero" length (e.g. ``on()``
-immediately followed by ``off()``, without a delay) are suppressed.
+replacement. For example, pulses of "zero" length (e.g. :meth:`TTLInOut.on`
+immediately followed by :meth:`TTLInOut.off`, without a delay) are suppressed.
 """
 
 import numpy
@@ -107,8 +107,8 @@ class TTLInOut:
     This should be used with bidirectional channels.
 
     Note that the channel is in input mode by default. If you need to drive a
-    signal, you must call ``output``. If the channel is in output mode most of
-    the time in your setup, it is a good idea to call ``output`` in the
+    signal, you must call :meth:`output`. If the channel is in output mode most of
+    the time in your setup, it is a good idea to call :meth:`output` in the
     startup kernel.
 
     There are three input APIs: gating, sampling and watching. When one
@@ -301,10 +301,10 @@ def sample_input(self):
     @kernel
     def sample_get(self):
         """Returns the value of a sample previously obtained with
-        ``sample_input``.
+        :meth:`sample_input`.
 
         Multiple samples may be queued (using multiple calls to
-        ``sample_input``) into the RTIO FIFOs and subsequently read out using
+        :meth:`sample_input`) into the RTIO FIFOs and subsequently read out using
         multiple calls to this function.
 
         This function does not interact with the time cursor."""
@@ -324,11 +324,11 @@ def sample_get_nonrt(self):
     @kernel
     def watch_stay_on(self):
         """Checks that the input is at a high level at the position
-        of the time cursor and keep checking until ``watch_done``
+        of the time cursor and keep checking until :meth:`watch_done`
         is called.
 
         Returns ``True`` if the input is high. A call to this function
-        must always be followed by an eventual call to ``watch_done``
+        must always be followed by an eventual call to :meth:`watch_done`
         (use e.g. a try/finally construct to ensure this).
 
         The time cursor is not modified by this function.
@@ -338,7 +338,7 @@ def watch_stay_on(self):
 
     @kernel
     def watch_stay_off(self):
-        """Like ``watch_stay_on``, but for low levels."""
+        """Like :meth:`watch_stay_on`, but for low levels."""
         rtio_output(now_mu(), self.channel, 3, 1)  # gate rising
         return rtio_input_data(self.channel) == 0
 
@@ -419,7 +419,7 @@ def set_mu(self, frequency):
 
     @kernel
     def set(self, frequency):
-        """Like ``set_mu``, but using Hz."""
+        """Like :meth:`set_mu`, but using Hz."""
         self.set_mu(self.frequency_to_ftw(frequency))
 
     @kernel

artiq/language/core.py

@@ -28,19 +28,20 @@ def kernel(arg=None, flags={}):
     This decorator marks an object's method for execution on the core
     device.
 
-    When a decorated method is called from the Python interpreter, the ``core``
+    When a decorated method is called from the Python interpreter, the :attr:`core`
     attribute of the object is retrieved and used as core device driver. The
     core device driver will typically compile, transfer and run the method
     (kernel) on the device.
 
     When kernels call another method:
-        - if the method is a kernel for the same core device, is it compiled
+
+        - if the method is a kernel for the same core device, it is compiled
           and sent in the same binary. Calls between kernels happen entirely on
           the device.
         - if the method is a regular Python method (not a kernel), it generates
           a remote procedure call (RPC) for execution on the host.
 
-    The decorator takes an optional parameter that defaults to ``core`` and
+    The decorator takes an optional parameter that defaults to :attr`core` and
     specifies the name of the attribute to use as core device driver.
 
     This decorator must be present in the global namespace of all modules using

artiq/language/environment.py

@@ -230,7 +230,7 @@ def build(self):
         instead: when the repository is scanned to build the list of
         available experiments and when the dataset browser ``artiq_browser``
         is used to open or run the analysis stage of an experiment. Do not
-        rely on being able to operate on devices or arguments in ``build()``.
+        rely on being able to operate on devices or arguments in :meth:`build`.
 
         Datasets are read-only in this method.
 
@@ -277,7 +277,7 @@ def get_device(self, key):
 
     def setattr_device(self, key):
         """Sets a device driver as attribute. The names of the device driver
-         and of the attribute are the same.
+        and of the attribute are the same.
 
         The key is added to the instance's kernel invariants."""
         setattr(self, key, self.get_device(key))
@@ -328,8 +328,10 @@ def get_dataset(self, key, default=NoDefault, archive=True):
         By default, datasets obtained by this method are archived into the output
         HDF5 file of the experiment. If an archived dataset is requested more
         than one time (and therefore its value has potentially changed) or is
-        modified, a warning is emitted. Archival can be turned off by setting
-        the ``archive`` argument to ``False``.
+        modified, a warning is emitted.
+
+        :param archive: Set to ``False`` to turn off archiving datasets obtained
+            by this method into the experiment's output HDF5 file. Default is ``True``
         """
         try:
             return self.__dataset_mgr.get(key, archive)
@@ -355,7 +357,7 @@ def prepare(self):
         """Entry point for pre-computing data necessary for running the
         experiment.
 
-        Doing such computations outside of ``run`` enables more efficient
+        Doing such computations outside of :meth:`run` enables more efficient
         scheduling of multiple experiments that need to access the shared
         hardware during part of their execution.
 
@@ -371,8 +373,8 @@ def run(self):
 
         This method may interact with the hardware.
 
-        The experiment may call the scheduler's ``pause`` method while in
-        ``run``.
+        The experiment may call the scheduler's :meth:`pause` method while in
+        :meth:`run`.
         """
         raise NotImplementedError
 
@@ -382,7 +384,7 @@ def analyze(self):
         This method may be overloaded by the user to implement the analysis
         phase of the experiment, for example fitting curves.
 
-        Splitting this phase from ``run`` enables tweaking the analysis
+        Splitting this phase from :meth:`run` enables tweaking the analysis
         algorithm on pre-existing data, and CPU-bound analyses to be run
         overlapped with the next experiment in a pipelined manner.
 
@@ -392,13 +394,14 @@ def analyze(self):
 
 
 class EnvExperiment(Experiment, HasEnvironment):
-    """Base class for top-level experiments that use the ``HasEnvironment``
-    environment manager.
+    """Base class for top-level experiments that use the
+    :class:`~artiq.language.environment.HasEnvironment` environment manager.
 
     Most experiments should derive from this class."""
     def prepare(self):
-        """The default prepare method calls prepare for all children, in the
-        order of instantiation, if the child has a prepare method."""
+        """This default prepare method calls :meth:`~artiq.language.environment.Experiment.prepare`
+        for all children, in the order of instantiation, if the child has a
+        :meth:`~artiq.language.environment.Experiment.prepare` method."""
         for child in self.children:
             if hasattr(child, "prepare"):
                 child.prepare()

artiq/protocols/asyncio_server.py

@@ -1,23 +1,25 @@
 import asyncio
+from abc import abstractmethod, ABC
 from copy import copy
 
 
-class AsyncioServer:
+class AsyncioServer(ABC):
     """Generic TCP server based on asyncio.
 
     Users of this class must derive from it and define the
-    ``_handle_connection_cr`` method and coroutine.
+    :meth:`~artiq.protocols.asyncio_server.AsyncioServer._handle_connection_cr`
+    method/coroutine.
     """
     def __init__(self):
         self._client_tasks = set()
 
     async def start(self, host, port):
         """Starts the server.
 
-        The user must call ``stop`` to free resources properly after this
-        method completes successfully.
+        The user must call :meth:`stop`
+        to free resources properly after this method completes successfully.
 
-        This method is a `coroutine`.
+        This method is a *coroutine*.
 
         :param host: Bind address of the server (see ``asyncio.start_server``
             from the Python standard library).
@@ -48,3 +50,7 @@ def _handle_connection(self, reader, writer):
         task = asyncio.ensure_future(self._handle_connection_cr(reader, writer))
         self._client_tasks.add(task)
         task.add_done_callback(self._client_done)
+
+    @abstractmethod
+    async def _handle_connection_cr(self, reader, writer):
+        pass

artiq/protocols/pc_rpc.py

@@ -1,7 +1,7 @@
 """
 This module provides a remote procedure call (RPC) mechanism over sockets
 between conventional computers (PCs) running Python. It strives to be
-transparent and uses ``artiq.protocols.pyon`` internally so that e.g. Numpy
+transparent and uses :mod:`artiq.protocols.pyon` internally so that e.g. Numpy
 arrays can be easily used.
 
 Note that the server operates on copies of objects provided by the client,
@@ -61,18 +61,18 @@ class Client:
     can be used as if they were local methods.
 
     For example, if the server provides method ``foo``, and ``c`` is a local
-    ``Client`` object, then the method can be called as: ::
+    :class:`.Client` object, then the method can be called as: ::
 
         result = c.foo(param1, param2)
 
-    The parameters and the result are automatically transferred with the
+    The parameters and the result are automatically transferred from the
     server.
 
     Only methods are supported. Attributes must be accessed by providing and
     using "get" and/or "set" methods on the server side.
 
     At object initialization, the connection to the remote server is
-    automatically attempted. The user must call ``close_rpc`` to
+    automatically attempted. The user must call :meth:`~artiq.protocols.pc_rpc.Client.close_rpc` to
     free resources properly after initialization completes successfully.
 
     :param host: Identifier of the server. The string can represent a
@@ -81,11 +81,11 @@ class Client:
     :param port: TCP port to use.
     :param target_name: Target name to select. ``IncompatibleServer`` is
         raised if the target does not exist.
-        Use ``AutoTarget`` for automatic selection if the server has only one
+        Use :class:`.AutoTarget` for automatic selection if the server has only one
         target.
         Use ``None`` to skip selecting a target. The list of targets can then
-        be retrieved using ``get_rpc_id`` and then one can be selected later
-        using ``select_rpc_target``.
+        be retrieved using :meth:`~artiq.protocols.pc_rpc.Client.get_rpc_id`
+        and then one can be selected later using :meth:`~artiq.protocols.pc_rpc.Client.select_rpc_target`.
     :param timeout: Socket operation timeout. Use ``None`` for blocking
         (default), ``0`` for non-blocking, and a finite value to raise
         ``socket.timeout`` if an operation does not complete within the
@@ -198,7 +198,7 @@ def __init__(self):
 
     async def connect_rpc(self, host, port, target_name):
         """Connects to the server. This cannot be done in __init__ because
-        this method is a coroutine. See ``Client`` for a description of the
+        this method is a coroutine. See :class:`artiq.protocols.pc_rpc.Client` for a description of the
         parameters."""
         self.__reader, self.__writer = \
             await asyncio.open_connection(host, port, limit=100*1024*1024)
@@ -447,7 +447,8 @@ def __str__(self):
 
 class Server(_AsyncioServer):
     """This class creates a TCP server that handles requests coming from
-    ``Client`` objects.
+    *Client* objects (whether :class:`.Client`, :class:`.BestEffortClient`,
+    or :class:`.AsyncioClient`).
 
     The server is designed using ``asyncio`` so that it can easily support
     multiple connections without the locking issues that arise in
@@ -591,7 +592,7 @@ def simple_server_loop(targets, host, port, description=None):
     """Runs a server until an exception is raised (e.g. the user hits Ctrl-C)
     or termination is requested by a client.
 
-    See ``Server`` for a description of the parameters.
+    See :class:`artiq.protocols.pc_rpc.Server` for a description of the parameters.
     """
     loop = asyncio.get_event_loop()
     try:

artiq/protocols/remote_exec.py

@@ -7,10 +7,10 @@
 with the experiment (and over the network).
 
 Controllers with support for remote execution contain an additional target
-that gives RPC access to instances of ``RemoteExecServer``. One such instance
+that gives RPC access to instances of :class:`.RemoteExecServer`. One such instance
 is created per client (experiment) connection and manages one Python namespace
 in which the experiment can execute arbitrary code by calling the methods of
-``RemoteExecServer``.
+:class:`.RemoteExecServer`.
 
 The namespaces are initialized with the following global values: