[GRASS-git] [OSGeo/grass] 687596: docs: Use backticks as literal in Sphinx (#6399)

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 6875961f516331a68aefe29d953ceabf58823d47
      https://github.com/OSGeo/grass/commit/6875961f516331a68aefe29d953ceabf58823d47
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-09-26 (Fri, 26 Sep 2025)

  Changed paths:
    M gui/wxpython/docs/wxgui_sphinx/conf.py
    M man/sphinx/conf.py
    M python/grass/docs/conf.py

  Log Message:
  -----------
  docs: Use backticks as literal in Sphinx (#6399)

Set the default role in Sphinx to literal so that backticks (not just double backticks) are interpreted as literal. Now they are interpreted as text in emphasis, but literal aligns that to Markdown use of backticks.

While backticks mean a different thing in Sphinx/reStructuredText and Markdown, Sphinx can be configured to produce the same thing as a typical Markdown rendering, using the default role. While in another world, having the default role as `py:obj` or `any` would be an interesting option, with all the Markdown around us, having backticks interpreted as literal or code is most advantageous because it removes the issues when switching between Sphinx with reStructuredText for Python and Markdown everywhere else (Doxygen also supports Markdown).

Relation to double backticks: The double backticks is unrelated to this in a sense that this changes how single backticks is interpreted (it changes the default role of it). Explicit roles before single backticks are not affected either. In other words, this is about roles, not about monospace/verbatim text.

Current code - good case: As for the current code, my assumption is that if any current code is using single backticks now, it indeed meant to use it for some sort of monospace code rendering, so this is correcting it.

Current code - bad case: The unset default role resulted in emphasis/italics in the current documentation. That would be appropriate for things like functions or objects. If describing an object was the intention of using single backticks (but explicit role `py:obj` was omitted), monospace is wrong, but not be a big mistake because it is still a code and it is still not linked anywhere (like before this change). In other words, linking symbols always required `py:obj` and proper way of doing emphasis/italics is not backticks, so these usages were wrong also before this change. From a search, these seem to be in minority, but there are some which are clearly meant as links to functions.



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications