Details
-
Type:
Bug
-
Status: Won't Fix
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: documenteer
-
Labels:None
-
Epic Link:
-
Team:SQuaRE
Description
I wrote
New configurations for :lsst-task:`lsst.meas.astrom.AstrometryTask` source and reference selectors
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
and ran stack-docs build. It said:
preparing documents... done
|
/Users/jds/Projects/LSST/src/pipelines_lsst_io/known-issues.rst:19: WARNING: unknown document: docker
|
releases/note-source/v17_0.rst:97: WARNING: undefined label: lsst.obs.lsst (if the link has no caption the label must precede a section header)
|
releases/note-source/v17_0.rst:125: WARNING: undefined label: lsst.pipe.base (if the link has no caption the label must precede a section header)
|
releases/note-source/v17_0.rst:125: WARNING: undefined label: lsst.daf.butler (if the link has no caption the label must precede a section header)
|
releases/note-source/v17_0.rst:262: WARNING: undefined label: lsst.log (if the link has no caption the label must precede a section header)
|
releases/note-source/v17_0.rst:320: WARNING: undefined label: lsst.display.firefly (if the link has no caption the label must precede a section header)
|
releases/note-source/v18_0_0.rst:118: WARNING: lsst-task could not find a reference to lsst.meas.astrom.AstrometryTask
|
releases/note-source/v18_0_0.rst:120: WARNING: lsst-task could not find a reference to lsst.meas.astrom.AstrometryTask
|
|
Traceback (most recent call last):
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/documenteer/sphinxrunner.py", line 85, in run_sphinx
|
app.build(force_all, filenames)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/application.py", line 325, in build
|
self.builder.build_all()
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 299, in build_all
|
self.build(None, summary='all source files', method='all')
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 403, in build
|
self.write(docnames, list(updated_docnames), method)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 440, in write
|
self._write_serial(sorted(docnames))
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 449, in _write_serial
|
self.write_doc(docname, doctree)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/html.py", line 607, in write_doc
|
ctx = self.get_doc_context(docname, body, metatags)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/html.py", line 574, in get_doc_context
|
toc = self.render_partial(self_toc)['fragment']
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/builders/html.py", line 398, in render_partial
|
pub.publish()
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/core.py", line 219, in publish
|
output = self.writer.write(self.document, self.destination)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/writers/__init__.py", line 80, in write
|
self.translate()
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/writers/html.py", line 56, in translate
|
self.document.walkabout(visitor)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/nodes.py", line 174, in walkabout
|
if child.walkabout(visitor):
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/nodes.py", line 174, in walkabout
|
if child.walkabout(visitor):
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/nodes.py", line 174, in walkabout
|
if child.walkabout(visitor):
|
[Previous line repeated 8 more times]
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/nodes.py", line 166, in walkabout
|
visitor.dispatch_visit(self)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
|
return method(node)
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/writers/html.py", line 882, in unknown_visit
|
raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
|
NotImplementedError: Unknown node: pending_task_xref
|
|
Exception occurred:
|
File "/Users/jds/sw/venv/docs/lib/python3.7/site-packages/sphinx/writers/html.py", line 882, in unknown_visit
|
raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
|
NotImplementedError: Unknown node: pending_task_xref
|
The full traceback has been saved in /var/folders/g9/5c5t1myd54scz1kz39g718b40000gn/T/sphinx-err-pgdmv8je.log, if you want to report the issue to the developers.
|
Please also report this if it was a user error, so that a better error message can be provided next time.
|
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
|
Removing the :lsst-task: resolves the issue.
I'm using:
$ python -c 'import documenteer; print(documenteer.__version__)'
|
0.5.0
|
Attachments
Activity
At the same time, you shouldn't be using any markup syntax in section titles (see https://developers.google.com/style/headings from our style guide).
I don't see that advice on that page (the nearest it gets is perhaps “Don't use code font”).
But regardless — NotImplementedError: Unknown node: pending_task_xref is an unfortunate outcome, regardless of what the style guide says. 
> Don't use code font
Yes, that's the gudeline I'm referring to. It means generally, "don't style text in headers."
I'll fix the error message.
John Swinbank, yes I can add an html visitor for the node to avoid this build failure. At the same time, you shouldn't be using any markup syntax in section titles (see https://developers.google.com/style/headings from our style guide).
The basic rational is that lsst-task exists to make a link. But having that link in a section title isn't as useful as it seems. It's not useful when that section title appears in a contents list because the whole title is a link, and it's distracting to users when they're trying to read the section's content.
So I can work on making sure accidentally adding lsst-task to a section header doesn't create a build failure, but this work would only be to strip the formatting from the section titles.