Skip to content

docs(referencing.rst): add additional data about :doc: role #13587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 8, 2025
Merged

docs(referencing.rst): add additional data about :doc: role #13587

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3c6d8c5
docs(referencing.rst): add additional data about :doc: role
vwheeler63 May 21, 2025
be1f9be
docs: re-wording per request.
vwheeler63 May 22, 2025
b29194a
docs: decided the 2nd version is more clear and complete.
vwheeler63 May 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions doc/usage/referencing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,9 @@ There is also a way to directly link to documents:
If no explicit link text is given (like usual: ``:doc:`Monty Python members
</people>```), the link caption will be the title of the given document.

Note that the string inside the single quotes must be a case-sensitive with
Copy link
Contributor

@timhoffm timhoffm May 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It’s more straightforward to integrate this in line 139 via

the document name is a case-sensitive relative or absolute path.

Or if you feel the need for more context

the document name can be a relative or absolute path and is always case-sensitive, even on windows.

Copy link
Member

@AA-Turner AA-Turner May 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How practical would it be to remove case-sensitivity? This seems like surprising behaviour.

Copy link
Contributor Author

@vwheeler63 vwheeler63 May 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or if you feel the need for more context

Done! I like the 2nd version better, because then no Windows users have to wonder whether it applies to them or not.

Copy link
Contributor

@timhoffm timhoffm May 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How practical would it be to remove case-sensitivity? This seems like surprising behaviour.

"Surprising" depends on your OS.

If we just make our internal handling case-insensitive, we'd can run into the following situation: Somebody uses sloppy casing because they are on windows and then somebody else tries to build on Linux and that fails because the file is not found.

I think we don't want that. So we'd have to add extra logic to care for OS that expect exact casing (such as, if don't find a file, search for files with other casing).

I believe being strict and requiring correct casing right away is the better approach.

Copy link
Contributor Author

@vwheeler63 vwheeler63 May 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe being strict and requiring correct casing right away is the better approach.

Interestingly, I find this to be true. Here is why: Of the many, many people that build the LVGL documents which is the most important place I use Sphinx (I do a lot of maintenance of those docs as well as the doc-build system [we do some programmatic "prep work" before Sphinx is launched]), there are only 2 of us with Windows systems and the others all have Linux, and we share the same code and files and—this may seem odd, but it is, in fact a real need:

  • it needs to FAIL on both platforms for the same reasons, and
  • when it works, it needs to work on both platforms.

I NEVER want to crank out a document set with its build system that does not also work on Linux!

Given that need, this behavior of the :doc: role is, in fact, in alignment with that. As it is the only interpreted text role (that I am aware of) that deals with "things" in the file system, it makes sense from a design perspective to keep Sphinx as cross-platform-compatible as possible.

P.S. Thank you @AA-Turner for the maintenance work you did with breathe!! That has helped everyone on the LVGL doc team! :-)

the file name, even on Windows.


Referencing downloadable files
------------------------------
Expand Down