Unknown SkipMarker directive when generating docs with autolink-skip block

[Zeitsperre]

Issue

When locally generating documentation that contains an autolink-skip:: directive with sphinx, I sometimes receive the following error:

/home/user/git/xclim/HISTORY.rst:267: WARNING: unknown node type: <SkipMarker: >                                                                                                                                                         

Exception occurred:Traceback (most recent call last):
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/cmd/build.py", line 277, in build_main
    app.build(args.force_all, filenames)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/application.py", line 349, in build
    self.builder.build_update()
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 301, in build_update
    self.build(to_build,
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 367, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 559, in write
    self._write_serial(sorted(docnames))
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 569, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/builders/html/__init__.py", line 665, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/writers/html.py", line 59, in translate
    self.document.walkabout(visitor)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/nodes.py", line 227, in walkabout
    if child.walkabout(visitor):
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/nodes.py", line 227, in walkabout
    if child.walkabout(visitor):
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/nodes.py", line 227, in walkabout
    if child.walkabout(visitor):
  [Previous line repeated 1 more time]
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/nodes.py", line 240, in walkabout
    visitor.dispatch_departure(self)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/sphinx/util/docutils.py", line 583, in dispatch_departure
    super().dispatch_departure(node)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/nodes.py", line 2034, in dispatch_departure
    return method(node)
  File "/home/user/miniconda3/envs/xclim/lib/python3.10/site-packages/docutils/nodes.py", line 2056, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.html5.HTML5Translator'> departing unknown node type: SkipMarker

This is not an issue when building my documentation on ReadTheDocs (using a pip or Anaconda-based environment). Could there maybe be a dependency missing for me locally?

Expected behavior

Not what you see above.

Steps to reproduce

$ git clone git@github.com:Ouranosinc/xclim.git
$ cd xclim
$ pip install xclim[dev]
$ make docs

The code block in question (in HISTORY.rst):

.. autolink-skip::
.. code-block:: python

    from xclim import sdba

    # NQ is the the number of equally spaced nodes, the argument previously given to nquantiles directly.
    EQM = sdba.EmpiricalQuantileMapping.train(
        ref, hist, nquantiles=sdba.equally_spaced_nodes(NQ, eps=1e-6), ...
    )

[felix-hilden]

Hi, thanks for reporting. Not having it on RTD would lead me to guess that something's not right in the local setup, or some package is screwing the thing. Could you try to build a minimal example to narrow down the causes? I'm talking conf.py + index.rst + requirements.txt + sphinx-build ... level minimal. It's pretty hard to know what's up otherwise.

For context, if you know Sphinx internals, here's where we remove the markers unconditinally. This should happen before the HTML translator gets to the doc tree.

[Zeitsperre]

Hi again,

I was able to resolve this issue by ensuring not to run sphinx-build -b linkcheck before building my documentation. I still find it to be an esoteric error that doesn't seem to have a clear source. In any case, I think this is likely within the greater scope of sphinx, so if it turns out to be an issue in the future, I'll follow up there.

Thanks again,