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
