Add proper cross-references in docs. #1101
Conversation
A few other minor spelling/grammar fixes, too. Tested using artiq-doc Conda environment Signed-off-by: Drew Risinger <drisinger+github@gmail.com>
| @@ -32,3 +32,6 @@ __pycache__/ | |||
| /dataset_db.pyon | |||
| /device_db*.py | |||
| /test* | |||
|
|
|||
| # Pycharm/Jetbrains Development | |||
| .idea/ | |||
There was a problem hiding this comment.
Please don't. You want to have those in your personal gitignore and not add everyone's favorite editor's temp files to every project.
| the ``archive`` argument to ``False``. | ||
| modified, a warning is emitted. | ||
|
|
||
| :param archive: Set to ``False`` to turn off archiving datasets obtained |
There was a problem hiding this comment.
"Set to False to prevent archival together with the run's results. Default is True" is a bit simpler and makes fewer assumptions about the workings of other parts of the codebase.
|
|
||
| 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` |
There was a problem hiding this comment.
Try to keep it < 80 chars line length.
| 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.""" |
There was a problem hiding this comment.
And put the final """ onto a line by itself if the docstring is longer than one line.
| 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 |
| 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`. |
| @@ -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 | |||
| @@ -70,11 +72,11 @@ If there are other experiments with higher priority (e.g. a high-priority timed | |||
| Otherwise, ``pause()`` returns immediately. | |||
| To check whether ``pause()`` would in fact *not* return immediately, use :meth:`artiq.master.scheduler.Scheduler.check_pause`. | |||
|
|
|||
| The experiment must place the hardware in a safe state and disconnect from the core device (typically, by using ``self.core.comm.close()``) before calling ``pause``. | |||
| The experiment must place the hardware in a safe state and disconnect from the core device (typically, by calling ``self.coredevice.comm.close()`` from the kernel, which is equivalent to :meth:`artiq.coredevice.core.Core.close`) before calling ``pause()``. | |||
There was a problem hiding this comment.
To fix my repeated confusion why we don't have pause() documented at all, Scheduler.pause() should probably be a stub method in the "root" Scheduler that we can cross-ref and document.
|
And I guess you tested those changes and crossref targets by running sphinx locally? |
Addresses m-labs#1102, m-labs#1102. User-interface issue, where users could put both -v and -q in to leave logging level unchanged.
Make -v/-q command line args mutually exclusive
Verbosity command line arg fix
There are several other instances in ARTIQ where a method has to be implemented by subclasses, but we're not using |
Based on PR #1101 by @drewrisinger
ONLY significant change is forcing AsyncioServer to inherit from AbstractBaseClass (ABC) to force its _handle_connection_cr() method to be implemented by subclasses.
A few other minor spelling/grammar fixes, too.
Tested using artiq-doc Conda environment
Signed-off-by: Drew Risinger drisinger+github@gmail.com