1

A colleague has pointed out to me this peculiar behavior. We use Sphinx to generate the HTML documentation of our project, and whenever we use the word 'module' in our text, this word is removed by the browser.

After some inspection, I have noticed that the word does appear in the source code of the HTML page:

enter image description here

but the rendered result looks like:

enter image description here

where clearly the word 'module' has been removed.

Further inspection on the html source code revealed the following javascript code which seems to be the culprit:

enter image description here

Therefore, I wonder who generates this script? Is it Sphinx or any of its extensions? Is there any workaround to get the word 'module' displayed in the rendered html?

This is the list of Sphinx extensions we have activated:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx_rtd_theme',
    'sphinx.ext.autosectionlabel',
    'sphinxcontrib.email',
    'sphinxcontrib.bibtex',
    'sphinx.ext.graphviz',
    'sphinx_git',
]

UPDATE:

I have found the real cause of my problem. For some reason which I ignore, I had a layout.html file in my /source/_templates folder. This file seems to be extending the default one (as in a way explained here), adding the javascript function that removes the word 'module'. Next step will be to find out how did that file get there...

Martí
  • 571
  • 6
  • 17
  • https://stackoverflow.com/questions/50361218/remove-the-word-module-from-sphinx-documentation There is your culprit – Roberto Zvjerković May 05 '21 at 17:20
  • indeed, that's the first post I saw after my first googling. As you can see, they do not really provide a solution to my problem, it seems to me quite a price to pay to sacrifice the use of such a common word in exchange of solving other issue with the autodoc functionality... – Martí May 05 '21 at 17:24
  • I'm saying that solution IS the problem. Somewhere in your code someone used that solution (which is terrible, mind you) which now created your problem. – Roberto Zvjerković May 05 '21 at 17:25
  • yes, you're right, that solution is now my problem. And apparently quite an extended one (I believe many people use the sphinx-apidoc) and makes me wonder how come this wasn't noticed before (or posted in SO, which is almost the same, haha) – Martí May 05 '21 at 17:32
  • not sure how sphinx works but in the worst case you can try to load a script before this inline script and remove this particular script tag from the dom before it runs. – The Fool May 05 '21 at 17:35
  • That script is not a part of sphinx... – Roberto Zvjerković May 05 '21 at 17:37
  • Isn't the problematic code part of a layout template? – Stuart May 05 '21 at 17:42
  • Actually, @Roberto, I think it is... now I have disabled all the extensions listed in my question and the problem persists. For a moment I thought it could be due to the ``sphinx-autobuild`` which keeps a server open monitoring for changes. But the problem is there even with the regular ``sphinx-build`` – Martí May 05 '21 at 17:58
  • However, I suspect this is only a problem for the HTML builder and not for the latex one, for instance. I still consider it a Sphinx-related issue, though. – Martí May 05 '21 at 17:59
  • Make sure you do a `make clean` first. Do not assume this is a Sphinx issue until you can prove it. For example, [Pyramid docs do not remove the word "module"](https://docs.pylonsproject.org/projects/pyramid/en/latest/search.html?q=module). It's also not [sphinx_rtd_theme](https://github.com/readthedocs/sphinx_rtd_theme/search?q=module). You can search the remaining plugin source code to find the culprit. – Steve Piercy May 06 '21 at 11:53
  • @Steve, sorry. I did not explain myself well. I did the following: 1) ``make clean source build``, 2) Comment out all the sphinx extensions in ``conf.py`` (``extensions = []``), 3) run ``sphinx-build -M html source build``. The result is the same. The word ``module``disappears from the sentence ``Hello this a module`` in the output, because the javascript code remains in the ``index.html`` source . I try to be cautious when making assumptions, but after steps (1), (2), and (3) it seems to me that something within Sphinx is producing that. Still I hope someone can shed some light here. Thanks – Martí May 06 '21 at 12:52
  • I have found the cause of the problem. I explain in the update at the bottom of my question. But I still ignore what was the cause of the cause of the problem. – Martí May 06 '21 at 13:41
  • Ah, the good ol' footgun strikes again! ;) If you have your project under version control, you can do a `git blame`. – Steve Piercy May 07 '21 at 07:17

1 Answers1

0

I seem to have come up with a workaround (although not the most satisfying solution)

I thought that this javascript code would work in a single-pass fashion, and therefore, typing 'modulemodule' instead of 'module' would result in the removal of one ocurrence, resulting in a final 'module'. And it has worked!

To make it slightly better, I have created a substitution as .. |module| replace:: modulemodule which I store in another file and include whenever needed. Now, I only need to write my sentence like Hello this is a |module|. (notice the double space between a and |module|)

Martí
  • 571
  • 6
  • 17