Bug#881554: Pending upload for python-configshell-fb?
On Thu, 2019-08-01 at 08:16 -0500, Kenneth Pronovici wrote: > > While epydoc can parse Javadoc comments, it seems that Sphinx does > > not > > support them. So I don't know how the documentation package for > > configshell-fb could be generated without epydoc. Maybe we can > > simply > > drop this package... > > It is possible to do this conversion in a semi-automated way. Back > in > the original bug report back in 2017, I provided [1], which is a > hack-ish script to convert common Epydoc markup to Google-style > docstrings that can be parsed by Sphinx. It's not perfect, but it > would get you much of the way toward working code. However, unless > you have time to take on that effort, I think it's probably going to > be simplest to just drop the documentation package - especially if > you > think that the API documentation in Debian is not heavily-used. I am inclined to do the same, to drop the documentation package. But Christophe did all the work in the past, so his opinion mattered. I will make an upload for this package dropping the -doc package. Thanks, Ritesh -- Ritesh Raj Sarraf | http://people.debian.org/~rrs Debian - The Universal Operating System signature.asc Description: This is a digitally signed message part
Bug#881554: Pending upload for python-configshell-fb?
> While epydoc can parse Javadoc comments, it seems that Sphinx does not > support them. So I don't know how the documentation package for > configshell-fb could be generated without epydoc. Maybe we can simply > drop this package... It is possible to do this conversion in a semi-automated way. Back in the original bug report back in 2017, I provided [1], which is a hack-ish script to convert common Epydoc markup to Google-style docstrings that can be parsed by Sphinx. It's not perfect, but it would get you much of the way toward working code. However, unless you have time to take on that effort, I think it's probably going to be simplest to just drop the documentation package - especially if you think that the API documentation in Debian is not heavily-used. [1] https://bitbucket.org/cedarsolutions/cedar-backup3/src/73037a2/util/sphinx-convert
Bug#881554: Pending upload for python-configshell-fb?
Hi Ritesh,
On Thu, 01 Aug 2019 17:43:25 +0530, Ritesh Raj Sarraf wrote :
> On Thu, 2019-08-01 at 11:55 +0200, Christophe Vu-Brugier wrote:
> > There is no bug report upstream, but I created a branch to remove the
> > epydoc dependency entirely a few days ago. This branch has not been
> > merge yet.
>
> So good to hear from you. :-)
>
> Glad that this is already reported upstream. But does those changes
> help with the documentation. Dropping epydoc is one part but then what
> else can/should we use as a replacement ?
From what I have seen, the epydoc markup in configshell-fb's docstrings
was not used to document the API. The epydoc markup was used as a
markup language to display help messages.
For instance, consider the help message for `ls` that is displayed when
the user types `help ls` in targetcli:
https://github.com/open-iscsi/configshell-fb/blob/master/configshell/node.py#L675
I{path} would have been displayed as italic in your console by the
render_domtree() giant function:
https://github.com/open-iscsi/configshell-fb/blob/master/configshell/console.py#L326
In truth, the "console" epydoc markup is not used because targetcli-fb
is built for Python 3 on Debian and cannot load epydoc.
With the epydoc specific markup removed, what is left is Javadoc
comments like:
'''
Initializes a Console instance.
@param stdin: The console standard input.
@type stdin: file object
@param stdout: The console standard output.
@type stdout: file object
'''
While epydoc can parse Javadoc comments, it seems that Sphinx does not
support them. So I don't know how the documentation package for
configshell-fb could be generated without epydoc. Maybe we can simply
drop this package... I don't think many developers read the API
documentation of configshell-fb.
With best regards,
--
Christophe Vu-Brugier
Bug#881554: Pending upload for python-configshell-fb?
Hi Christophe, On Thu, 2019-08-01 at 11:55 +0200, Christophe Vu-Brugier wrote: > There is no bug report upstream, but I created a branch to remove the > epydoc dependency entirely a few days ago. This branch has not been > merge yet. So good to hear from you. :-) Glad that this is already reported upstream. But does those changes help with the documentation. Dropping epydoc is one part but then what else can/should we use as a replacement ? -- Ritesh Raj Sarraf | http://people.debian.org/~rrs Debian - The Universal Operating System signature.asc Description: This is a digitally signed message part
Bug#881554: Pending upload for python-configshell-fb?
Hi Ritesh, On Thu, 01 Aug 2019 14:24:59 +0530, Ritesh Raj Sarraf wrote : > Hello Kenneth, > > On Wed, 2019-07-31 at 21:17 -0500, Kenneth Pronovici wrote: > > Hi, > > > > I just wanted to follow up on python-configshell-fb. Back in June, > > you marked a pending upload to remove the epydoc dependency, but the > > bug is still open. I've filed the package removal request for > > epydoc, and I'm working through all of the reverse dependencies to > > adjust them, so the package removal can proceed. Could you please > > upload your new package sometime soon? It would help simplify things > > for me. > > So I didn't pay very close attention back when I disabled the > dependency on epydoc. > > Thing is, we are shipping a package for the documentation, python- > configshell-fb-doc, which contains the epydoc generated documentation > files. If I drop the epydoc dependency, I am left with an empty package > that I'll have to drop. I would rather prefer to see it still carry the > documentation. > > I just checked on the upstream project page and didn't see any bug > reports about the unmaintained epydoc dependency. Maybe they are > unaware of epydoc's current state. There is no bug report upstream, but I created a branch to remove the epydoc dependency entirely a few days ago. This branch has not been merge yet. See: https://github.com/open-iscsi/configshell-fb/pull/51 > I think best would be to migrate the documentation to the new sphinx > format you mentioned some time back. As for the documentation, there is not much epydoc markup in configshell-fb. It is mostly used to extract the message for the help commands from the docstrings (e.g. `help ls`, `help create`) and nicely format it to the console. Except that the nice formatting does not work most of the time because configshell-fb and targetcli-fb are running on Python 3 where epydoc is missing. Hope that helps, > My knowledge on documentation is very limited and so is the time these > days. So, if you can help me (or upstream directly) here, that'd help > expedite the upload without the epydoc dependency. > > Thanks, > Ritesh > -- Christophe Vu-Brugier
Bug#881554: Pending upload for python-configshell-fb?
Hello Kenneth, On Wed, 2019-07-31 at 21:17 -0500, Kenneth Pronovici wrote: > Hi, > > I just wanted to follow up on python-configshell-fb. Back in June, > you marked a pending upload to remove the epydoc dependency, but the > bug is still open. I've filed the package removal request for > epydoc, and I'm working through all of the reverse dependencies to > adjust them, so the package removal can proceed. Could you please > upload your new package sometime soon? It would help simplify things > for me. So I didn't pay very close attention back when I disabled the dependency on epydoc. Thing is, we are shipping a package for the documentation, python- configshell-fb-doc, which contains the epydoc generated documentation files. If I drop the epydoc dependency, I am left with an empty package that I'll have to drop. I would rather prefer to see it still carry the documentation. I just checked on the upstream project page and didn't see any bug reports about the unmaintained epydoc dependency. Maybe they are unaware of epydoc's current state. I think best would be to migrate the documentation to the new sphinx format you mentioned some time back. My knowledge on documentation is very limited and so is the time these days. So, if you can help me (or upstream directly) here, that'd help expedite the upload without the epydoc dependency. Thanks, Ritesh -- Ritesh Raj Sarraf | http://people.debian.org/~rrs Debian - The Universal Operating System signature.asc Description: This is a digitally signed message part
Bug#881554: Pending upload for python-configshell-fb?
Hi, I just wanted to follow up on python-configshell-fb. Back in June, you marked a pending upload to remove the epydoc dependency, but the bug is still open. I've filed the package removal request for epydoc, and I'm working through all of the reverse dependencies to adjust them, so the package removal can proceed. Could you please upload your new package sometime soon? It would help simplify things for me. Thanks, KEN -- Kenneth J. Pronovici
