sphinx autodoc creates blank page on readthedocs, but correctly includes module docstring locally - python-sphinx

I'm getting different results from autodoc when I run sphinx locally (versions 1.6.6 or 2.0.1 on Anaconda Python 3.6.8 for Mac) than when I run it on readthedocs.org (according to their log it's Sphinx version 1.8.5, and probably Python 2.7 since it's launched with python rather than python3).
The difference is in the results from the following file, Shady.Text.rst, which contains no more than:
Shady.Text Sub-module
=====================
.. automodule:: Shady.Text
Now, this sub-module happens to contain only a module-level docstring and no member docstrings—that's as intended, so the corresponding html page should contain the module docstring and no more. And this is exactly what happens when I run make html locally. However the result at https://shady.readthedocs.io/en/latest/source/Shady.Text.html is content-free (header only, no module docstring).
FWIW my autodoc-related entries in conf.py are:
autoclass_content = 'both'
autodoc_member_order = 'groupwise'
What am I doing wrong?

Thanks #StevePiercy for drawing my attention to the crucial lines in the raw log file:
WARNING: autodoc: failed to import module u'Text' from module u'Shady'; the module executes module level statement and it might call sys.exit().
WARNING: autodoc: failed to import module u'Video' from module u'Shady'; the module executes module level statement and it might call sys.exit().
(I had searched the 9000-line log file for .Text, because Text on its creates too many hits, but it hadn't occurred to me to search it for 'Text' in quotes).
To me, the message is misleading: the problem is not that "the module executes module level statements" because that per se is allowed. I wasted some time after noting that some module-level statements seemed to be allowed in other sub-modules, and tried to bundle the offending module-level statements into a class decorator thinking maybe sphinx's mysterious module-level-statement-detector would miss them then...)
No, the problem is that not the fact that the module-level statements exist and might call sys.exit(), but the fact that they did indirectly call sys.exit() during sphinx's compilation procedure. This was a quirk of the way I handle missing dependencies, which should probably be re-thought, but I could work around it for now by avoiding my sys.exit() call when os.environ.get('READTHEDOCS') is truthy.

Related

Python Module metric_exporter Not Found

I'm relatively new to Opentelemetry. I've followed many tutorials including opentelemetry.io but I keep running into dependency problems with the python stack.
Currently I keep running into
"No module named 'opentelemetry.exporter.otlp.proto.grpc.metric_exporter'".
I have all the python modules loaded after running "opentelemetry-bootstrap --action=install" but still that module is not found. I'm not new to python and I've traced into the code and can not find why that module is not found even though I see it at:
"opentelemetry/opentelemetry-python-1.12.0rc1/exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc"
Am I doing something wrong?

sphinx autofunction works fine on local but not on server

The autofunction works perfectly on my local machine but on server it does not show anything. I check the log and find the following thing,
WARNING: autodoc: failed to import function blablabla; the following exception was raised: No module named 'numpy'.
I suppose installing packages is not a must on sphinx. I only need sphinx to read my docstring and generate documentation.
Well, after several hours of investigation I am able to answer my question. Using autodoc_mock_imports does the trick.

WEBrick run on hanami 1.0.0 shows errors because of wrong inflection

I generated model with hanami generate model stimulus. Then I fixed "stimuluses" to "stimuli" in the migration file name and inside, the table name.
Everytime I load a page I get this error in the server console window:
[ROM::Relation[Stimuluses]] failed to infer schema. Make sure tables exist before ROM container is set up. This may also happen when your migration tasks load ROM container, which is not needed for migrations as only the connection is required (schema parsing returned no columns, table "stimuluses" probably doesn't exist)
I looked into the libraries and found that this functionality has Inflecto library. Then I tried both adding to hanami project this:
# /config/initializers/inflecto.rb
require 'inflecto'
Inflecto.inflections do |inflect|
inflect.irregular('stimulus', 'stimuli')
end
And editing the defualt library file:
# gems/inflecto-0.0.2/lib/inflecto/defaults.rb
Inflecto.inflections do |inflect|
...
inflect.irregular('stimulus', 'stimuli')
...
end
But the message is still there after restarting the server.
Is this something I should solve and if yes, how to do this?
EDIT:
Also tried:
# /config/initializers/inflector.rb
require 'hanami/utils/inflector'
Hanami::Utils::Inflector.inflections do
exception 'stimulus', 'stimuli'
end
I'm assuming we are talking about Hanami v1.0.0, right?
You nearly succeeded. What hit you is that initializers seem to be not loaded when executing hanami commands and maybe a bug in code reloading. So instead of an initializer put it into a file that gets loaded when hanami commands are executed or require the initializer file in such a place. E.g.,
# config/initializers/inflections.rb
require 'hanami/utils/inflector'
Hanami::Utils::Inflector.inflections do
exception 'stimulus', 'stimuli'
end
and then in your environment file
# config/environment.rb
# ...
require_relative 'initializers/inflections.rb'
# ...
I'm not sure if that is a good place to put custom inflection rules, but at least it works.

sphinx-autogen unable to find module

I'm trying to implement one of the answers to this question. However, I haven't been successful because when I run
> sphinx-autogen -o generated *.rst
I get the errors
Failed to import 'MyMod.X': no module named MyMod.X
Failed to import 'MyMod.Y': no module named MyMod.Y
Failed to import 'MyMod.Z': no module named MyMod.Z
Within my .rst files, there is one with the line:
.. automodule:: MyMod.X
(and similarly for MyMod.Y and MyMod.Z).
I'm running this within a subdirectory docs. In the parent directory containing docs, there is also a subdirectory MyMod which contains __init__.py, X.py, Y.py, and Z.py. The conf.py file within docs has the line sys.path.insert(0, os.path.abspath('../')) immediately after import sys.
The closest related question I can find is this, but the answers there seem to suggest that it is solved by inserting '../' into the path, which I had already done. Also, sphinx-autobuild can find these modules happily, so I don't think this is the issue.
Interestingly, changing the line in my .rst file to be .. automodule:: ../MyMod.X gets rid of the error message, though nothing seems to be generated in the directory I expect, and I then get error messages in sphinx-autobuild.
How can I get sphinx-autogen to read in these modules?
if anyone else has a better answer, or an explanation for this please post it, but here is what I learned about my question
Although sphinx-autogen gives error messages, in the case that I was looking at, the files I was trying to get it to create were still created. While it could not find the modules (and indeed, they were functions, not modules, so it's not a surprise that it couldn't), it still produced the expected output.

Pylint: "locally defined disables" still give warnings. How to suppress them?

I work with a software framework which has a couple of classes with method names containing capital letters (due to C++ wrappers). This is of course not PEP8 and pylint shows the corresponding error C0103. I also added C0111 to the list to ignore the missing docstrings for some methods, like this:
def Configure(self): # pylint: disable=C0103,C0111
It works, however now I get warnings because of the local disablings:
Class: I0011 -> locally disabling C0103
Class: I0011 -> locally disabling C0111
How should I suppress them?
OK, so obviously one has to ignore the ignore-warning explicitly. One can do this in the pylint config file: if you don't have one, simply generate a standard configuration via
pylint --generate-rcfile > pylint.rc
and uncomment the line with disable=... and add I0011 to the list. This suppresses all warnings regarding "locally defined disablings".
The other method is to add the following line to the beginning of a file (or block, whatever), if you don't want to suppress the warning globally:
#pylint: disable=I0011

Resources