Bug#932584: Epydoc and Pydoctor
Kenneth Pronovici writes ("Re: Epydoc and Pydoctor"):
> I decided to NMU and uploaded a few days ago, so things are in good
> shape now, I think. You can integrate my changes whenever you have
> time. Thanks for confirming that your ok with the NMU. I was
> hoping you would be.
Thank you for this. However, you did an upload with binaries and it
therefore isn't migrating. I will do a source-only upload right away.
Regards,
Ian.
--
Ian JacksonThese opinions are my own.
If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.
Bug#932584: Epydoc and Pydoctor
Hi Kenneth, Ian, On Wed, Jul 31, 2019 at 08:45:54PM -0500, Kenneth Pronovici wrote: > On Wed, Jul 31, 2019 at 10:46 AM Ian Jackson > wrote: > > > Otherwise, I will see if I can determine how well the package works > > > without epydoc installed. If it works (i.e. doesn't blow up) and I > > > don't hear back with other instructions, I will eventually NMU my > > > changes to remove the epydoc dependency. Given that I haven't gotten > > > any replies for more than 18 months now, I won't wait that long before > > > doing this NMU. > > > > That sounds really good to me for now. I think you can do this NMU > > whenever you like. > > I tested pydoctor against my own cedar-backup2 code, which I never converted > away from Epydoc since it's Python 2-only. It seems to work fine: > > mars:~/projects/dev/software/cedar-backup2> pydoctor CedarBackup2/ > adding directory > /home/pronovic/projects/dev/software/cedar-backup2/CedarBackup2 > 41/41 modules processed 0 warnings > WARNING: guessing CedarBackup2 for project name > writing html to apidocs using pydoctor.templatewriter.writer.TemplateWriter > starting ModuleIndexPage ... > Error trying to import 'epytext' parser: > > ImportError: No module named epydoc.markup.epytext > > Using plain text formatting only. > took 0.006452s > starting ClassIndexPage ... took 0.011512s > starting IndexPage ... took 0.002281s > starting NameIndexPage ... took 0.079562s > starting UndocumentedSummaryPage ... took 0.004314s > 125/125 pages written > Generating objects inventory at apidocs/objects.inv > > The generated HTML documentation is legible, if not as pretty as it > would have been before. Given that it works, I am going to NMU the > version of the package that doesn't depend on epydoc. I'll also > create a PR on salsa. On salsa, master has diverged from the released > package, but I am *not* going to integrate those changes, because I > don't want to take responsibility for them. Sorry for the delayed reply and thanks for working on Pydoctor without epydoc. I'm happy for you to NMU a new version, but can also merge a patch and do an upload - as you prefer. As far as I know pydoctor upstream is pretty dormant, but not completely inactive. Pull requests do get looked at and there is the occasional fix to keep it running, but that's about it. Cheers, Jelmer
Bug#932584: Epydoc and Pydoctor
I decided to NMU and uploaded a few days ago, so things are in good shape now, I think. You can integrate my changes whenever you have time. Thanks for confirming that your ok with the NMU. I was hoping you would be. KEN
Bug#932584: Epydoc and Pydoctor
On Wed, Jul 31, 2019 at 10:46 AM Ian Jackson wrote: > > Otherwise, I will see if I can determine how well the package works > > without epydoc installed. If it works (i.e. doesn't blow up) and I > > don't hear back with other instructions, I will eventually NMU my > > changes to remove the epydoc dependency. Given that I haven't gotten > > any replies for more than 18 months now, I won't wait that long before > > doing this NMU. > > That sounds really good to me for now. I think you can do this NMU > whenever you like. I tested pydoctor against my own cedar-backup2 code, which I never converted away from Epydoc since it's Python 2-only. It seems to work fine: mars:~/projects/dev/software/cedar-backup2> pydoctor CedarBackup2/ adding directory /home/pronovic/projects/dev/software/cedar-backup2/CedarBackup2 41/41 modules processed 0 warnings WARNING: guessing CedarBackup2 for project name writing html to apidocs using pydoctor.templatewriter.writer.TemplateWriter starting ModuleIndexPage ... Error trying to import 'epytext' parser: ImportError: No module named epydoc.markup.epytext Using plain text formatting only. took 0.006452s starting ClassIndexPage ... took 0.011512s starting IndexPage ... took 0.002281s starting NameIndexPage ... took 0.079562s starting UndocumentedSummaryPage ... took 0.004314s 125/125 pages written Generating objects inventory at apidocs/objects.inv The generated HTML documentation is legible, if not as pretty as it would have been before. Given that it works, I am going to NMU the version of the package that doesn't depend on epydoc. I'll also create a PR on salsa. On salsa, master has diverged from the released package, but I am *not* going to integrate those changes, because I don't want to take responsibility for them. KEN -- Kenneth J. Pronovici
Bug#932584: Epydoc and Pydoctor
Kenneth Pronovici writes ("Epydoc and Pydoctor"):
> (I'm the maintainer for epydoc.)
Hi.
Thanks for the analysis which seems to make sense to me.
> Given that epydoc does not work properly in Python 3, and it's beyond
> my capabilities to fix it, there aren't too many options here. Either
> we remove pydoctor's dependency on epydoc, or we remove pydoctor from
> the archive.
>
> I don't see any evidence that upstream is developing a Python 3
> version of this code. This means that python-pydoctor will have to be
> removed from the archive eventually. Maybe now is the time to do it?
I had a quick look at Sources in some random sid chroot and the
following Build-Depend on it:
git-buildpackage
kiwi
libcloud
subvertpy
(and there are no rdepends).
AFAICT pydoctor was written for Twisted but Twisted no longer seems to
use it ? But here
https://wiki.python.org/moin/DocumentationTools
it is still listed and not in the dead section. The Python 3 issue
https://github.com/twisted/pydoctor/issues/96
is not encouraging.
IDK if anyone here is in close enough contact with the upstream Python
world to know whether pydoctor is dead or not.
> Otherwise, I will see if I can determine how well the package works
> without epydoc installed. If it works (i.e. doesn't blow up) and I
> don't hear back with other instructions, I will eventually NMU my
> changes to remove the epydoc dependency. Given that I haven't gotten
> any replies for more than 18 months now, I won't wait that long before
> doing this NMU.
That sounds really good to me for now. I think you can do this NMU
whenever you like.
Ian.
--
Ian JacksonThese opinions are my own.
If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.
Bug#932584: Epydoc and Pydoctor
(I'm the maintainer for epydoc.)
I took a pass through the pydoctor code. The epydoc module is
imported in pydoctor/html.py, where it's an optional import:
try:
from epydoc.markup import epytext
EPYTEXT = True
except:
print "no epytext found"
EPYTEXT = False
Later on, in the doc2html() method, the code checks EPYTEXT and falls
back on a boring docstring implementation ("Generate an HTML
representation of a docstring in a really boring way") if the module
isn't available. This file has a docstring which says "The old HTML
generator. Deprecated, do not use", so it may not be relevant.
The epydoc module is also imported in pydoctor/epydoc2stan.py:
def get_parser(formatname):
try:
mod = __import__('epydoc.markup.' + formatname,
globals(), locals(), ['parse_docstring'])
except ImportError, e:
return None, e
else:
return mod.parse_docstring, None
Like html.py, epydoc2stan.py falls back on a boring docstring method
if get_parser() returns None.
Based on this analysis, it seems to me that epydoc isn't a strict
dependency for pydoctor. I think that pydoctor should still continue
to work even without the epydoc module available, albeit with somewhat
different output.
Given that epydoc does not work properly in Python 3, and it's beyond
my capabilities to fix it, there aren't too many options here. Either
we remove pydoctor's dependency on epydoc, or we remove pydoctor from
the archive.
I don't see any evidence that upstream is developing a Python 3
version of this code. This means that python-pydoctor will have to be
removed from the archive eventually. Maybe now is the time to do it?
Otherwise, I will see if I can determine how well the package works
without epydoc installed. If it works (i.e. doesn't blow up) and I
don't hear back with other instructions, I will eventually NMU my
changes to remove the epydoc dependency. Given that I haven't gotten
any replies for more than 18 months now, I won't wait that long before
doing this NMU.
KEN
--
Kenneth J. Pronovici
