Clean up docs handling

.circleci/config.yml

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

.github/workflows/main.yml

@@ -69,4 +69,5 @@ jobs:
  - name: Build documentation
  run: |
  pip install .[sphinx]
- sphinx-build docs docs_build --color -W -bhtml
+ cd docs
+ make html SPHINXOPTS="-W"

.gitignore

@@ -27,6 +27,10 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# Autogenerated docs
+docs/reference/config_options.rst
+docs/changelog.md
+
 # PyInstaller
 # Usually these files are written by a python script from a template
 # before PyInstaller builds the exe, so as to inject date/other infos into it.

.pre-commit-config.yaml

@@ -5,36 +5,30 @@ ci:
 repos:
 
  - repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v4.0.1
+ rev: v4.1.0
  hooks:
  - id: check-yaml
  - id: end-of-file-fixer
  - id: trailing-whitespace
  # - id: check-json
 
- - repo: https://github.com/mgedmin/check-manifest
- rev: "0.46"
- hooks:
- - id: check-manifest
- additional_dependencies: [setuptools>=46.4.0]
-
  - repo: https://github.com/pycqa/isort
- rev: 5.9.3
+ rev: 5.10.1
  hooks:
  - id: isort
 
  - repo: https://github.com/asottile/pyupgrade
- rev: v2.25.0
+ rev: v2.31.1
  hooks:
  - id: pyupgrade
  args: [--py36-plus]
 
  - repo: https://github.com/psf/black
- rev: 21.7b0
+ rev: 22.3.0
  hooks:
  - id: black
 
  - repo: https://gitlab.com/pycqa/flake8
- rev: 3.9.1
+ rev: 3.9.2
  hooks:
  - id: flake8

MANIFEST.in

@@ -22,7 +22,7 @@ exclude codecov.yml
 graft examples
 
 # docs subdirs we want to skip
-prune docs/build
+prune docs/_build
 prune docs/gh-pages
 prune docs/dist
 

docs/autogen_config.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+"""
+autogen_config.py
+
+Create config_options.rst, a Sphinx documentation source file.
+Documents the options that may be set in nbconvert's configuration file,
+jupyter_nbconvert_config.py.
+
+"""
+import os
+import os.path
+
+from nbclient.cli import NbClientApp
+
+header = """\
+
+.. This is an automatically generated file.
+.. do not modify by hand.
+
+.. _other-full-config:
+
+Config file and command line options
+====================================
+Jupyter ``nbclient`` can be run with a variety of command line arguments.
+A list of available options can be found below in the :ref:`options section
+<options>`.
+
+.. _options:
+
+Options
+-------
+This list of options can be generated by running the following and hitting
+enter::
+
+ $ jupyter execute --help-all
+
+"""
+
+try:
+ indir = os.path.dirname(__file__)
+except NameError:
+ indir = os.getcwd()
+
+destination = os.path.join(indir, "reference/config_options.rst")
+
+with open(destination, "w") as f:
+ app = NbClientApp()
+ f.write(header)
+ f.write(app.document_config_options())

docs/client.rst

@@ -135,7 +135,7 @@ there are no execution errors. But, what if there are errors?
 Execution until first error
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 An error during the notebook execution, by default, will stop the execution
-and raise a ``CellExecutionError``. Conveniently, the source cell causing
+and raise a `CellExecutionError`. Conveniently, the source cell causing
 the error and the original error name and message are also printed.
 After an error, we can still save the notebook as before::
 

docs/conf.py

@@ -181,3 +181,7 @@ def setup(app):
  HERE = os.path.abspath(os.path.dirname(__file__))
  dest = os.path.join(HERE, 'changelog.md')
  shutil.copy(os.path.join(HERE, '..', 'CHANGELOG.md'), dest)
+
+ autogen_config = os.path.join(HERE, "autogen_config.py")
+ with open(autogen_config) as f:
+ exec(compile(f.read(), autogen_config, "exec"), {})

docs/reference/index.rst

@@ -7,4 +7,5 @@ This part of the documentation lists the full API reference of all public classe
  :maxdepth: 2
 
  nbclient
+ config_options
  modules

nbclient/cli.py

@@ -68,7 +68,7 @@ class NbClientApp(JupyterApp):
  help=dedent(
  """
  When a cell raises an error the default behavior is that
- execution is stopped and a `CellExecutionError`
+ execution is stopped and a :py:class:`nbclient.exceptions.CellExecutionError`
  is raised.
  If this flag is provided, errors are ignored and execution
  is continued until the end of the notebook.

nbclient/client.py

@@ -123,7 +123,7 @@ class NotebookClient(LoggingConfigurable):
  help=dedent(
  """
  If ``False`` (default), when a cell raises an error the
- execution is stopped and a `CellExecutionError`
+ execution is stopped and a ``CellExecutionError``
  is raised, except if the error name is in
  ``allow_error_names``.
  If ``True``, execution errors are ignored and the execution
@@ -153,8 +153,8 @@ class NotebookClient(LoggingConfigurable):
  ``allow_errors`` or ``allow_error_names`` configurable options 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
+ explicitly allowed, a ``CellExecutionError`` will be raised.
+ If True, ``CellExecutionError`` will be raised for any error that occurs
  while executing the notebook. This overrides the ``allow_errors``
  and ``allow_error_names`` options and the ``raises-exception`` cell
  tag.
@@ -279,7 +279,7 @@ class NotebookClient(LoggingConfigurable):
  """
  A callable which executes after the kernel manager and kernel client are setup, and
  cells are about to execute.
- Called with kwargs `notebook`.
+ Called with kwargs ``notebook``.
  """
  ),
  ).tag(config=True)
@@ -290,7 +290,7 @@ class NotebookClient(LoggingConfigurable):
  help=dedent(
  """
  A callable which executes after the kernel is cleaned up.
- Called with kwargs `notebook`.
+ Called with kwargs ``notebook``.
  """
  ),
  ).tag(config=True)
@@ -301,7 +301,7 @@ class NotebookClient(LoggingConfigurable):
  help=dedent(
  """
  A callable which executes when the notebook encounters an error.
- Called with kwargs `notebook`.
+ Called with kwargs ``notebook``.
  """
  ),
  ).tag(config=True)
@@ -313,7 +313,7 @@ class NotebookClient(LoggingConfigurable):
  """
  A callable which executes before a cell is executed and before non-executing cells
  are skipped.
- Called with kwargs `cell` and `cell_index`.
+ Called with kwargs ``cell`` and ``cell_index``.
  """
  ),
  ).tag(config=True)
@@ -324,7 +324,7 @@ class NotebookClient(LoggingConfigurable):
  help=dedent(
  """
  A callable which executes just before a code cell is executed.
- Called with kwargs `cell` and `cell_index`.
+ Called with kwargs ``cell`` and ``cell_index``.
  """
  ),
  ).tag(config=True)
@@ -336,7 +336,7 @@ class NotebookClient(LoggingConfigurable):
  """
  A callable which executes after a cell execution is complete. It is
  called even when a cell results in a failure.
- Called with kwargs `cell` and `cell_index`.
+ Called with kwargs ``cell`` and ``cell_index``.
  """
  ),
  ).tag(config=True)
@@ -347,8 +347,8 @@ class NotebookClient(LoggingConfigurable):
  help=dedent(
  """
  A callable which executes when a cell execution results in an error.
- This is executed even if errors are suppressed with `cell_allows_errors`.
- Called with kwargs `cell` and `cell_index`.
+ This is executed even if errors are suppressed with ``cell_allows_errors``.
+ Called with kwargs ``cell` and ``cell_index``.
  """
  ),
  ).tag(config=True)

setup.cfg

@@ -4,6 +4,7 @@ universal=0
 [check-manifest]
 ignore =
  .circleci*
+ docs/changelog.md
 
 [flake8]
 ignore = E203,E731,F811,W503