1

This works fine as long as I don't need a specific section - and this seems to work: name <page.html>_, except if I repeat name Sphinx throws

WARNING: Duplicate explicit target name: "name"

and even if it's harmless, it populates the screen quickly in my application.

image1

I'm aware of raw HTML-based workarounds, but that's a discouraged practice; is there a more "native" approach?

Example:

  • `docs <package.html#module-package.callbacks>`_ (works)

  • :doc:`docs <package.html#module-package.callbacks>` (doesn't)

  • :doc:`docs <package#module-package.callbacks>` (doesn't)

bad_coder
  • 11,289
  • 20
  • 44
  • 72
OverLordGoldDragon
  • 1
  • 9
  • 53
  • 101
  • The question was deleted with a cited reason that wasn't at all applicable; there is no "typo" here, and comment responses did not address the problem. – OverLordGoldDragon Sep 11 '20 at 13:50
  • This is a your own package's documentation, right? If so, use the [Python domain](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain). – Steve Piercy Sep 11 '20 at 14:07
  • I would like to ask what this means: "it populates the screen quickly in my application"? I don't know how to understand the sentence? – bad_coder Sep 11 '20 at 14:31
  • @StevePiercy [Exact context](https://dev-tg.readthedocs.io/en/latest/why_deeptrain.html); I presume you refer to `py:module::`; have an example syntax where I can hyperlink a reference to `deeptrain.html#module-deeptrain.callbacks` via "docs"? (i.e. [docs](https://dev-tg.readthedocs.io/en/latest/deeptrain.html#module-deeptrain.callbacks)) – OverLordGoldDragon Sep 11 '20 at 14:41
  • @bad_coder [`sphinx-build`](https://i.imgur.com/ucZBU50.png) – OverLordGoldDragon Sep 11 '20 at 14:42
  • @OverLordGoldDragon ok I'm going to try and take a look at this, but I'm not making any promises I'll be able to solve it. – bad_coder Sep 11 '20 at 14:47
  • Is this what you are looking for? https://stackoverflow.com/a/22714510/407651 – mzjn Sep 11 '20 at 14:48
  • @OverLordGoldDragon ok, I understand the exact problem you are having which is also in part circumstancial. I'll take a few minutes to write an answer with an example. – bad_coder Sep 11 '20 at 14:55
  • @mzjn No; needs to have labels and be able to reference a section by `id` (e.g. url `#name`) – OverLordGoldDragon Sep 11 '20 at 15:13
  • I don't understand what the problem is. Why do you link to HTML pages? The native approach would be to link to 1) named *.rst files, or 2) labels defined in *.rst files, or 3) code objects as defined by the Python domain. A proper [mcve] would make it easier to understand. – mzjn Sep 11 '20 at 15:16
  • @mzjn "Why" - because that's the relevant section on a page; this is a non-issue with HTML and Markdown. Again, I have a section with a header (which has an HTML `id` tag, allowing jumping to that part of the page via `#` in URL), and wish to link to it directly. I also linked the exact context. What remains unclear? – OverLordGoldDragon Sep 11 '20 at 15:18
  • Again: the "native" approach to linking would not involve any HTML pages at all, it would all be done using RST constructs. So no, I still don't get it. – mzjn Sep 11 '20 at 15:22
  • @mzjn Whatever results in "I click on label X and it takes me to .rst file Y and scrolls to section Z" works for me; an HTML hyperlink is just one way of doing it. – OverLordGoldDragon Sep 11 '20 at 15:23
  • Take some time to consider the pros/cons as I try to convey them in the answer. There's several perspectives that should be considered in this matter. – bad_coder Sep 11 '20 at 16:38

1 Answers1

1

I don't think it's a good approach to use intersphinx if your aim is cross-referencing your project internally.

At this point it has to be noticed: When using one of the autodoc directives like automodule or autoclass, that Python object is placed in the Sphinx index and can be cross-referenced.

But this raises a question: How to cross-reference ReST sections? It's considered an arbitrary location because they aren't objects, and they aren't inserted in the Sphinx index by the autodoc directives (or through a py domain declaration in your .rst).

Well, in that case there are 4 main options to consider (the last may be the least obvious, and thus the most important):

  1. Use a ReST hyperlink targets directly above the section.
  2. Use Python domain reference directly to the autodoc directive below the section.
  3. Use a cross-reference to the document if the section sits on the top of the .rstfile.

Last but not least:

  1. Consider you have 1 .rst file that documents one or several packages (lets say your_package.utils). Normal ReST rules have you place 1 section on the top of the file. But there isn't an automodule directive because, probably, the package is an empty __init__.py without a docstring...So what's the best solution in that case?
*****************
your_package.UTIL
*****************

.. py:module:: your_package.UTIL


Modules
=======

(...the usual stuff...)

OK!!! Now, by explicitly declaring your_package.util at above or below the ReST section as a Python module (or any Python object that may apply) what happens??? It gets inserted in the Sphinx index!!! Why is that important?? Because you can cross-reference it as a Python module (packages are, after all, modules) and don't have to cross-reference it as a document, or as a section. Which gives overall consistency to your documentation, index, and cross-referencing...

End result? You never see HTML or anchors..!! Sphinx manages/generates/indexes all of that for you. And that's what you really want. A complete abstraction layer.

Some people would raise objections:

  • "You are putting Sphinx/ReST inside your Python docstrings (people don't know how to read that)."

Easily solved, put the plain English in the Docstring and ReST/Sphinx syntax in the .rst files (autodoc will join the parts).

  • Others would object:"I want HTML in my ReST!"

Sure enough, but whenever you edit or refactor something it's doomed to become a pain. And who said normal Python/ReST developers looking at your stuff know anything -or want to look at- HTML or anchors?

So the soundest separation goes along these lines.

About using duplicate target names:

There's no real reason to use duplicate target names. A refactor done from your IDE is better served by unique target names. If you decide to move the ReST section the target above simply goes with it.

.. _this_section_without_duplicate_name:

*****************
Your ReST section
*****************

:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`

No anchors needed. Much cleaner and slick.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
  • 1
    Thanks for the writeup. I sought a method without inserting explicit references, but suppose Sphinx doesn't work that way. A `:doc:` or `:py:doc:` also gets rendered [as code](https://i.stack.imgur.com/rjUiN.png), rather than a hyperlink, which isn't desired. I'm willing to insert the references, but what would you suggest of the rendering - how can I refer to a _module_ with a hyperlink-looking clickable? – OverLordGoldDragon Sep 11 '20 at 18:39
  • @OverLordGoldDragon I'll have to look into it, probably later tonight or tomorrow morning. I'd rather defer any comment on how the links are rendered visually after making some experiments. – bad_coder Sep 11 '20 at 18:44
  • 1
    Use a custom style to override the code style. See https://stackoverflow.com/a/63820734/2214933 – Steve Piercy Sep 12 '20 at 06:01
  • @OverLordGoldDragon using RTD-theme. `:doc:` and `:ref:` should render as normal URL's without the box style (but `:mod:` or `:obj:` have the box). Using `:any:` will identify the type of Python object, use the appropriate role, and the box style gets applied. (Notice a module is a Python type, not just a HTML page.) If you want to get rid of the box, 3 options: 1- Locally override custom style. 2. Use a target plus `:ref:` 3. Put that module/package in its own .rst and use `:doc:` instead of `:mod:`. (PS. There is no `py:doc:` there's a `py:mod:` and there is a `:doc:` that's not py.) – bad_coder Sep 12 '20 at 23:20
  • @OverLordGoldDragon sorry for the late answer. It's Saturday... – bad_coder Sep 12 '20 at 23:24
  • Notice [:doc:](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc) uses path syntax to find `.rst` files while [py:mod:](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#role-py-mod) uses doted syntax to find package.module.class...The reader will expect consistency, a "visual box" if referencing an object while a bare URL references a document. Dilema becomes: What to do when the `.rst` document (or section) documents a package/object?? Do you want a "box" look, or URL look? Because this adds an apparent contradiction with the toctree look. – bad_coder Sep 12 '20 at 23:51
  • @StevePiercy Can this be done without affecting any _other_ code? i.e. only affect `:doc:` or whatever I decide to use to hyperlink. – OverLordGoldDragon Sep 13 '20 at 11:34
  • @bad_coder I'm using `sphinx_rtd_theme`. For option 1, I'd repeat my previous comment. Opt 2: can this be done for modules ([example](https://dev-tg.readthedocs.io/en/latest/deeptrain.html#module-deeptrain.callbacks))? -- and no probs @ late, you're still early by SE standards. – OverLordGoldDragon Sep 13 '20 at 11:37
  • @OverLordGoldDragon according to good etiquette, at this point you should open a new question. I just went through the [RTD tag](https://stackoverflow.com/questions/tagged/read-the-docs) and what I told you in the comments hasn't been asked nor answered. It's also a complete Q&A by itself about using the rtd-theme style. – bad_coder Sep 13 '20 at 12:55
  • @bad_coder You're right. Alright, ultimately think I'll just put up with the warnings as they seem harmless, or find a way to nuke them - but will keep your post in mind in a future effort. – OverLordGoldDragon Sep 13 '20 at 12:59
  • Did you try it out? You can also add a specific style to a block with the [class](https://docutils.sourceforge.io/docs/ref/rst/directives.html#class) directive. – Steve Piercy Sep 14 '20 at 12:48