Pydoc support/helper

[Sardorbek Imomaliev]

Currently pydoc doesn't work by default because it requires django requries django.setup() to be called. So to use it you need to provide some helper script like in this example ​https://stackoverflow.com/questions/24772805/python-documentation-for-django-views-generic-with-pydoc

import django
import pydoc
import os

os.environ['DJANGO_SETTINGS_MODULE'] = 'dummy.settings'
django.setup()
pydoc.cli()

Another issue(probably need to create separate for this one) is that when GDAL is not installed you can't use pydoc even after you have added helper script, because GDAL has to be setup properly on import and there is no way to make django skip this check. This also prevents running code analyzing tools like mypy on django without GDAL, which I don't think is required for running linters.

I don't know how many people are still using pydoc. But I think this should be supported because it is internal python documentation tool. How can I help with resolving this? Maybe django should provide management command for this?

[Mariusz Felisiak]

pydoc works perfectly fine for me, e.g.

$ pip install Django
$ pydoc django.views.generic

Help on package django.views.generic in django.views:

NAME
    django.views.generic

PACKAGE CONTENTS
    base
    dates
    detail
    edit
    list

CLASSES
    builtins.Exception(builtins.BaseException)
...

[Sardorbek Imomaliev]

Issue occurs when trying to lookup models

python -mpydoc django.contrib.auth.models
problem in django.contrib.auth.models - ImproperlyConfigured: Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

[Sardorbek Imomaliev]

Also for gis

python -mpydoc django.contrib.gis.db.models
problem in django.contrib.gis.db.models - ImproperlyConfigured: Could not find the GDAL library (tried "gdal", "GDAL", "gdal2.3.0", "gdal2.2.0", "gdal2.1.0", "gdal2.0.0", "gdal1.11.0"). Is GDAL installed? If it is, try setting GDAL_LIBRARY_PATH in your settings.

[Mariusz Felisiak]

Yes, that's true. pydoc just like sphinx.ext.viewcode (see #29942) imports modules, that's why it will crash when required packages are missing or if settings are not configured. Setting DJANGO_SETTINGS_MODULE fixes this issue in most cases. I don't see a clear path to solve this in Django. I'm against adding a new management command for ​pydoc and adding multiple if __name__ == ... seems clunky and decrease code readability.

Maybe a discussion on DevelopersMailingList will bring some ideas, but I don't think it's feasible without side-effects.

Thanks for the report.