DOC: A few reST syntactic changes

.circleci/config.yml

@@ -24,7 +24,7 @@ jobs:
  - run:
  name: Build docs to store
  command: |
- sphinx-build -b html docs/ docs/_build/html
+ sphinx-build -W -b html docs/ docs/_build/html
 
  - store_artifacts:
  path: docs/_build/html/

docs/client.rst

@@ -164,9 +164,9 @@ argument::
 
 This widget rendering is not performed against a browser during execution, so
 only widget default states or states manipulated via user code will be
-calculated during execution. `%%javascript` cells will execute upon notebook
+calculated during execution. ``%%javascript`` cells will execute upon notebook
 rendering, enabling complex interactions to function as expected when viewed by
 a UI.
 
 If you can't view widget results after execution, you may need to select
-`Trust Notebook` under the `File` menu.
+:menuselection:`Trust Notebook` under the :menuselection:`File` menu.

docs/conf.py

@@ -39,6 +39,8 @@
  'myst_parser',
 ]
 
+autodoc_mock_imports = ['pytest', 'nbconvert', 'testpath']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -85,6 +87,7 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+default_role = 'any'
 
 # -- Options for HTML output ----------------------------------------------
 

docs/index.rst

@@ -10,6 +10,7 @@ Welcome to nbclient
 .. image:: https://codecov.io/github/jupyter/nbclient/coverage.svg?branch=master
  :alt: CodeCov
  :target: https://codecov.io/github/jupyter/nbclient
+
 ---
 
 **NBClient** is a tool for executing Jupyter Notebooks.

nbclient/client.py

@@ -49,8 +49,8 @@ class NotebookClient(LoggingConfigurable):
  The time to wait (in seconds) for output from executions.
  If a cell execution takes longer, a TimeoutError is raised.
 
- `None` or `-1` will disable the timeout. If `timeout_func` is set,
- it overrides `timeout`.
+ ``None`` or ``-1`` will disable the timeout. If ``timeout_func`` is set,
+ it overrides ``timeout``.
  """
  ),
  ).tag(config=True)
@@ -65,10 +65,10 @@ class NotebookClient(LoggingConfigurable):
  executions. If a cell execution takes longer, a TimeoutError
  is raised.
 
- Returning `None` or `-1` will disable the timeout for the cell.
- Not setting `timeout_func` will cause the preprocessor to
- default to using the `timeout` trait for all cells. The
- `timeout_func` trait overrides `timeout` if it is not `None`.
+ Returning ``None`` or ``-1`` will disable the timeout for the cell.
+ Not setting ``timeout_func`` will cause the preprocessor to
+ default to using the ``timeout`` trait for all cells. The
+ ``timeout_func`` trait overrides ``timeout`` if it is not ``None``.
  """
  ),
  ).tag(config=True)
@@ -99,10 +99,10 @@ class NotebookClient(LoggingConfigurable):
  False,
  help=dedent(
  """
- If `False` (default), when a cell raises an error the
+ If ``False`` (default), when a cell raises an error the
  execution is stopped and a `CellExecutionError`
  is raised.
- If `True`, execution errors are ignored and the execution
+ If ``True``, execution errors are ignored and the execution
  is continued until the end of the notebook. Output from
  exceptions is included in the cell output in both cases.
  """
@@ -114,14 +114,14 @@ class NotebookClient(LoggingConfigurable):
  help=dedent(
  """
  If False (default), errors from executing the notebook can be
- allowed with a `raises-exception` tag on a single cell, or the
- `allow_errors` configurable option for all cells. An allowed error
+ allowed with a ``raises-exception`` tag on a single cell, or the
+ ``allow_errors`` configurable option for all cells. An allowed error
  will be recorded in notebook output, and execution will continue.
  If an error occurs when it is not explicitly allowed, a
  `CellExecutionError` will be raised.
  If True, `CellExecutionError` will be raised for any error that occurs
  while executing the notebook. This overrides both the
- `allow_errors` option and the `raises-exception` cell tag.
+ ``allow_errors`` option and the ``raises-exception`` cell tag.
  """
  ),
  ).tag(config=True)
@@ -142,10 +142,10 @@ class NotebookClient(LoggingConfigurable):
  False,
  help=dedent(
  """
- If `False` (default), then the kernel will continue waiting for
+ If ``False`` (default), then the kernel will continue waiting for
  iopub messages until it receives a kernel idle message, or until a
  timeout occurs, at which point the currently executing cell will be
- skipped. If `True`, then an error will be raised after the first
+ skipped. If ``True``, then an error will be raised after the first
  timeout. This option generally does not need to be used, but may be
  useful in contexts where there is the possibility of executing
  notebooks with memory-consuming infinite loops.
@@ -157,7 +157,7 @@ class NotebookClient(LoggingConfigurable):
  True,
  help=dedent(
  """
- If `True` (default), then the state of the Jupyter widgets created
+ If ``True`` (default), then the state of the Jupyter widgets created
  at the kernel will be stored in the metadata of the notebook.
  """
  ),
@@ -167,7 +167,7 @@ class NotebookClient(LoggingConfigurable):
  True,
  help=dedent(
  """
- If `True` (default), then the execution timings of each cell will
+ If ``True`` (default), then the execution timings of each cell will
  be stored in the metadata of the notebook.
  """
  ),
@@ -203,9 +203,9 @@ class NotebookClient(LoggingConfigurable):
  default_value='graceful',
  help=dedent(
  """
- If `graceful` (default), then the kernel is given time to clean
- up after executing all cells, e.g., to execute its `atexit` hooks.
- If `immediate`, then the kernel is signaled to immediately
+ If ``graceful`` (default), then the kernel is given time to clean
+ up after executing all cells, e.g., to execute its ``atexit`` hooks.
+ If ``immediate``, then the kernel is signaled to immediately
  terminate.
  """
  ),
@@ -215,12 +215,12 @@ class NotebookClient(LoggingConfigurable):
  default_value=':memory:',
  help="""Path to file to use for SQLite history database for an IPython kernel.
 
- The specific value `:memory:` (including the colon
+ The specific value ``:memory:`` (including the colon
  at both end but not the back ticks), avoids creating a history file. Otherwise, IPython
  will create a history file for each kernel.
 
  When running kernels simultaneously (e.g. via multiprocessing) saving history a single
- SQLite file can result in database errors, so using `:memory:` is recommended in
+ SQLite file can result in database errors, so using ``:memory:`` is recommended in
  non-interactive contexts.
  """,
  ).tag(config=True)
@@ -326,7 +326,7 @@ def start_kernel_manager(self) -> KernelManager:
  Returns
  -------
  kc : KernelClient
- Kernel client as created by the kernel manager `km`.
+ Kernel client as created by the kernel manager ``km``.
  """
  if not self.kernel_name:
  kn = self.nb.metadata.get('kernelspec', {}).get('name')
@@ -366,14 +366,14 @@ async def async_start_new_kernel_client(self, **kwargs) -> t.Tuple[KernelClient,
  Parameters
  ----------
  kwargs :
- Any options for `self.kernel_manager_class.start_kernel()`. Because
+ Any options for ``self.kernel_manager_class.start_kernel()``. Because
  that defaults to AsyncKernelManager, this will likely include options
- accepted by `AsyncKernelManager.start_kernel()``, which includes `cwd`.
+ accepted by ``AsyncKernelManager.start_kernel()``, which includes ``cwd``.
 
  Returns
  -------
  kc : KernelClient
- Kernel client as created by the kernel manager `km`.
+ Kernel client as created by the kernel manager ``km``.
  kernel_id : string-ized version 4 uuid
  The id of the started kernel.
  """
@@ -421,7 +421,7 @@ def setup_kernel(self, **kwargs) -> t.Generator:
  """
  Context manager for setting up the kernel to execute a notebook.
 
- The assigns the Kernel Manager (`self.km`) if missing and Kernel Client(`self.kc`).
+ The assigns the Kernel Manager (``self.km``) if missing and Kernel Client(``self.kc``).
 
  When control returns from the yield it stops the client's zmq channels, and shuts
  down the kernel.
@@ -445,7 +445,7 @@ async def async_setup_kernel(self, **kwargs) -> t.AsyncGenerator:
  """
  Context manager for setting up the kernel to execute a notebook.
 
- This assigns the Kernel Manager (`self.km`) if missing and Kernel Client(`self.kc`).
+ This assigns the Kernel Manager (``self.km``) if missing and Kernel Client(``self.kc``).
 
  When control returns from the yield it stops the client's zmq channels, and shuts
  down the kernel.
@@ -498,11 +498,12 @@ async def async_execute(
  Parameters
  ----------
  kwargs :
- Any option for `self.kernel_manager_class.start_kernel()`. Because
+ Any option for ``self.kernel_manager_class.start_kernel()``. Because
  that defaults to AsyncKernelManager, this will likely include options
- accepted by `AsyncKernelManager.start_kernel()``, which includes `cwd`.
+ accepted by ``jupyter_client.AsyncKernelManager.start_kernel()``,
+ which includes ``cwd``.
 
- `reset_kc` if True, the kernel client will be reset and a new one
+ ``reset_kc`` if True, the kernel client will be reset and a new one
  will be created (default: False).
 
  Returns
@@ -807,7 +808,7 @@ def process_message(
  Processes a kernel message, updates cell state, and returns the
  resulting output object that was appended to cell.outputs.
 
- The input argument `cell` is modified in-place.
+ The input argument *cell* is modified in-place.
 
  Parameters
  ----------

nbclient/tests/test_client.py

@@ -17,7 +17,6 @@
 from .. import NotebookClient, execute
 from ..exceptions import CellExecutionError
 
-import IPython
 from traitlets import TraitError
 from nbformat import NotebookNode
 from jupyter_client.asynchronous import AsyncKernelClient
@@ -35,7 +34,6 @@
 addr_pat = re.compile(r'0x[0-9a-f]{7,9}')
 ipython_input_pat = re.compile(r'<ipython-input-\d+-[0-9a-f]+>')
 current_dir = os.path.dirname(__file__)
-IPY_MAJOR = IPython.version_info[0]
 
 
 class AsyncMock(Mock):
@@ -117,7 +115,7 @@ def prepare_cell_mocks(*messages, reply_msg=None):
  """
  This function prepares a executor object which has a fake kernel client
  to mock the messages sent over zeromq. The mock kernel client will return
- the messages passed into this wrapper back from `preproc.kc.iopub_channel.get_msg`
+ the messages passed into this wrapper back from ``preproc.kc.iopub_channel.get_msg``
  callbacks. It also appends a kernel idle message to the end of messages.
  """
  parent_id = 'fake_id'
@@ -235,7 +233,7 @@ def assert_notebooks_equal(expected, actual):
 def notebook_resources():
  """
  Prepare a notebook resources dictionary for executing test
- notebooks in the `files` folder.
+ notebooks in the ``files`` folder.
  """
  return {'metadata': {'path': os.path.join(current_dir, 'files')}}