Skip to content

inline triple backtick foo.bar in doc comment incorrectly identifies foo as lang, stripping it in docs #17314

@timotheecour

Description

@timotheecour

Example

when true:
  ##[
  a1 ```foo.bar```

  a2
  ```foo
  bar
  ```
  ]##

Current Output

doc comment in nim code:

same code as comment but in rst file:

Expected Output

current output (stripping foo in the 1st foo.bar is incorrect; it looks like it's interpretting foo as the language of a markdown block but that seems incorrect (eg stackoverflow doesn't do that)

the question is whether to treat this case as markdown emulation or rst:

  • if treating as markdown emulation, it should render
foo.bar
  • if treating as rst, it should render with backticks, using double backticks `` as delimiters:
`foo.bar`

We should do what's best for nim here if there's an ambiguity.
This ties into how to escape single backticks /cc @a-mr refs #17260:

  • if we use rst interpretation, this gives a way to render backticks
  • if we use markdown interpretation, then to render backticks we'd need to do as follows:
## ``` `foo.bar` ```

(the leading and trailing space are stripped out; it's a markdown feature)

Additional Information

pip3 install rst2html
cat t11956d.rst | rst2html.py > /tmp/z01.html
generates:

image

1.5.1 2f213db

Metadata

Metadata

Assignees

No one assigned

    Labels

    Documentation GenerationRelated to documentation generation (but not content).

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions