pawamoy
commented
2 years ago Hello @tijuca, thank you very much for the detailed report! I think it will be enough to debug the issue :slightly_smiling_face:
My first intuition is that the repository root appears in sys.path, and therefore when trying to import netbox, pytkdocs actually imports from <root>/netbox instead of <root>/netbox/netbox. This issue is kind of why so many Python developers put their sources into an src folder (it's commonly called the "src layout").
To fix this, multiple solutions:
- rename the first netbox folder to src, or create a new src folder and move netbox into it. I think it won't easily be accepted :sweat_smile: But that would be good practice IMO.
- don't run mkdocs in the repository root, to avoid the side-effect of having the current working directory in
sys.path - manipulate
sys.pathin the legacy handlersetup_commandsto actually remove the repository root fromsys.path, or at least put the netbox folder in front of the repository root (higher precedence). I think it's the most sensible thing to do in your situation. Maybe not the best long-term solution though.
Keep me posted!
tijuca
Describe the bug On building the HTML documentation for netbox (while writing version 3.2.4) I've run into a error message about a non found module which is available within a subfolder from the netbox modules main folder.
Upstream is using python-legacy and not python-handlers together with griffe.
System information:
mkdocstrings: 0.19.0mkdocstrings-python (legacy): 0.2.3pytkdocs: 0.16.1To Reproduce It's probably not that easy to reproduce the issue I see as I'm currently trying to build the netbox documentation not within a venv but on a native Debian system. To make this possible I've packaged and updated various depending packages like also mkdocstrings, pytkdocs and also python-legacy.
I compared the binary packages on PyPi with the packages I've build locally and so far the content is the same. The shipped test suites are running successfully while a package build. Also most of the output while running
mkdocs build ...looks quite correct, except for modules that living in a subfolder that is named the same as the main foldernetbox.A cutted build log:
I was able to build the documentation with previous versions of mkdocstrings 0.17.0 , python-handler 0.6.6 and python-legacy 0.2.2.
I've searched a lot about the correct usage to aad a correct search path but I had no luck to get the build successfull running. The output is the same if I use
or the current setting from the upstream configuration for
mkdocs.yml. So my guess is currently that the issue I see is mostly because something isn't working correctly inside mkdocstring-python-legacy.The folder structure of the Python files is basically this:
I can't see why mkdoctrings is thinking that were are no modules
(netbox/)netbox/...but seems to have no problems to find modules in(netbox/)utilities/...e.g..Please let me know how to show you better to reproduce the issue if it's not obvious what I mean. I'm absolutely not that deep in the internals how mkdocstrings is working, but adding some more debug output in some of the modules I'm able to add of course. :-)
Additional context I haven't tried yet to build the documantion of netbox within a venv yet as I was busy with doing all the packaging work until now.