XMLWordPrintable

#### Details

• Type: Bug
• Status: Won't Fix
• Resolution: Done
• Fix Version/s: None
• Component/s:
• Labels:
None
• 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:

Removing the :lsst-task: resolves the issue.

I'm using:

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

#### Activity

Hide
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
Hide
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
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
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
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:
Jonathan Sick
Reporter:
John Swinbank
Watchers:
John Swinbank, Jonathan Sick