Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-20377

Can't use :lsst-task: in section headings

    Details

    • Type: Bug
    • Status: To Do
    • Resolution: Unresolved
    • Fix Version/s: None
    • Component/s: documenteer
    • Labels:
      None

      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.

      See also https://ci.lsst.codes/blue/organizations/jenkins/sqre%2Finfra%2Fdocumenteer/detail/documenteer/522/pipeline.

      I'm using:

      $ python -c 'import documenteer; print(documenteer.__version__)'
      0.5.0
      

        Attachments

          Activity

          Hide
          jsick Jonathan Sick added a comment -

          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.

          Show
          jsick Jonathan Sick added a comment - 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.
          Hide
          swinbank John Swinbank added a comment -

          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.

          Show
          swinbank John Swinbank added a comment - 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.
          Hide
          jsick Jonathan Sick added a comment -

          >  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.

          Show
          jsick Jonathan Sick added a comment - >  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.

            People

            • Assignee:
              jsick Jonathan Sick
              Reporter:
              swinbank John Swinbank
              Watchers:
              John Swinbank, Jonathan Sick
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:

                Summary Panel