Search code examples
pythonpycharmdocumentationpython-os

Documentation URL of os module

I'm trying to crack the URL format for Python's os module for use in PyCharm's documentation window.

My attempt so far:

https://docs.python.org/3/library/os.html#{element.qname}

but I'm having trouble displaying documentations such as:

https://docs.python.org/3/library/os.path.html#module-os.path

What's the right format?

Solution

  • Before addressing the URL hack, it should be mentioned that the deciding setting of how documentation is shown is the "Render external documentation for stdlib" setting. You can configure it by going to File > Settings > Python Integrated Tools > Docstrings > Render external documentation for stdlib as shown in the screenshot:

    enter image description here

    1. If you enable the "Render external documentation for stdlib" setting (and have internet access), the IDE will automatically retrieve standard library docs from https://docs.python.org/{python.version}/library/{module.name}.html#{element.qname}. The Python version is automatically determined from the Python interpreter configured for the Project, so that's the version of the documentation shown for the file you have opened in the editor.

    enter image description here

    See how this corresponds to the online documentation:

    enter image description here

    1. If you disable the "Render external documentation for stdlib" setting (or don't have internet access), the IDE will show the docstrings of its integrated stub files.

    enter image description here

    Having said that, the documentation tool window does not require configuring the URL for standard library modules (e.g. for the os, sys, etc...) contrary to how it's necessary for other libraries' External Documentation. In fact, there is no option in the IDE settings to change the address for standard library modules.

    What's the right format?

    The complete format would be:

    https://docs.python.org/{python.version}/library/{module.name}.html#{element.qname}

    crack the URL format for Python's os module for use in PyCharm's documentation window.

    This can be done, but it is limited to specific modules. It can not be done for the whole standard library because the base Module Name field would have to be left empty and in that case the IDE will ignore the setting.

    enter image description here

    If you use the hack for a specific module, the IDE will show the docstrings in the documentation tool window (like in example 2) but if you click the external link it will open the browser in the address configured in the external documentation. See the screenshot:

    enter image description here

    So the hack has limited usefulness.

    The hack can be used with offline docs if you download the Python HTML documentation (but it would still be limited to only showing documentation like in example 2). In that use case the correct way to write the URL would depend on OS/Shell/Browser, for Windows/CMD/Firefox you could use the below URL but there's no way to escape the hash # sign so the anchor won't work, but you'll be taken to the documentation page.

    file:///C:/directory_name/library/{module.name}.html#{element.qname}