[Django] #31744: Pydoc support/helper
Django
-----------------------------------------------+------------------------
Reporter: Sardorbek Imomaliev | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.0
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------------+------------------------
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
{{{
#!python
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?
--
Ticket URL: <https://code.djangoproject.com/ticket/31744>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: Sardorbek Imomaliev | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.0
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by felixxm):
`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)
...
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/31744#comment:1>
Django
-------------------------------------+-------------------------------------
Reporter: Sardorbek Imomaliev | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.0
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/31744#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Sardorbek Imomaliev | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.0
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/31744#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Sardorbek Imomaliev | Owner: nobody
Cleanup/optimization |
Component: Core (Other) | Version: 3.0
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by felixxm):
* status: new => closed
* resolution: => wontfix
* component: Documentation => Core (Other)
* type: Uncategorized => Cleanup/optimization
Comment:
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 [https://docs.python.org/3/library/pydoc.html 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/31744#comment:4>