naiquevin / sphinx-doc.el Goto Github PK

Sphinx has an extension, numpydoc, which enables a very popular docstring style that is used by numpy, scipy, and many other packages. It would be nice if sphinx-doc could generate docstrings using the syntax of numpydoc.

Hi !

I have discovered the existence of https://github.com/robodair/pydocstring.
Instead of re-invented the wheel, I think it could be worth replacing the current sphinx-doc backend by the pydocstring one.
What do you think @naiquevin ?
I can make a proof of concept draft PR if necessary.

for eg.

    :param pygerrit.client.GerritClient client: Gerrit client object

The existing docstring goes away when trying to update it.

These are valid Sphinx fields and may be added by the user later so it makes sense to retain them when a docstring is updated even though they were not added initially

Hi:

I just installed the elisp package from MELPA, and tried using it with my Python code. I keep getting the following error message when attempting to insert a new docstring into my code, and additionally, it always kills any existing docstring inside it, instead of updating it.

Suspicious state from syntax checker python-pycompile: Checker python-pycompile returned non-zero exit code 1, but no errors from output: Sorry: IndentationError: ('unexpected indent', ('/tmp/flycheck15795ZS0/app_utils.py', 84, 9, '         callback = mari.utils.connec()\n')) Checker definition probably flawed.

Is there anything I can do to resolve this?

Thanks!

When I apply C-c M-d it creates the doc section having new line at the end. Would it be possible to ignore the newline that applid at the end of docs?

Example output:

"""TODO describe function

:param provider:
:param _from:
:param job:
:returns:

"""

Wanted:

"""TODO describe function

:param provider:
:param _from:
:param job:
:returns:
"""

The init-value parameter for define-minor-mode is set to t. This enables the mode in non-python buffers as well, which is unfortunate. As far as I can tell from the documentation of define-minor-mode, there is no reason to set it to t initially. As with other minor modes, I'd prefer to enable it from python-mode-hook.

Before:

def helloworld():
    pass

after:

def helloworld():
    """TODO describe function

    :returns:

    """
    pass

Instead, for an empty function can we remove returns: value and we have more compact as follows:

def helloworld():
    """TODO describe function."""
    pass

Are you thinking on support this style?

http://www.sphinx-doc.org/en/stable/ext/napoleon.html#napoleon-marching-toward-legible-docstrings

Thanks!

could you please create a tag to use this package using melpa stable [1].
Thanks

[1] : http://stable.melpa.org/

In some codebases I have seen that trailing commas are used in function definitions, especially when functions take a lot of keyword parameters and people frequently change or add them. Trailing commas then help with version control and guard against forgotten commas. You might argue whether this is good stile, but the following is valid python:

def foo(arg1, arg2, arg3,):
    return bar

sphinx-doc then fails, because sphinx-doc-fun-args creates an empy string "" as the last arg. I fixed that in place by just removing empty strings from the argument list with remove "". But maybe there is a better place to implement a fix. I didn't go really went into understanding your code, so I refrained from a PR.

(defun sphinx-doc-fun-args (argstrs)
  "Extract list of arg objects from string ARGSTRS.
ARGSTRS is the string representing function definition in Python.
Note that the arguments self, *args and **kwargs are ignored."
  (when (not (string= argstrs ""))
    (mapcar #'sphinx-doc-str->arg
            (-filter
             (lambda (str)
               (and (not (string= (substring str 0 1) "*"))
                    (not (string= str "self"))))
             (remove ""
              (mapcar #'s-trim
                      (split-string argstrs ",")))))))

Is it possible to insert rst skeletons instead of numpydoc?

can you please tell me how do you make the demo gift ? really cool.

Consider the example:

def test(a="1%"):
    pass

This will fail with error sphinx-doc-fun-args: Not enough arguments for format string

I have some function that have PyLint control comments after their definition:

def some_func(param, param):  # pylint: disable=unused-variable
    pass

Calling sphinx-doc doesn’t do anything, not even an error message is printed.

It would be nice to have functions that automatically generate a skeleton for 'warning' and 'note'. For example:

    def function(array, key):
        """
        This function does ...

        .. warning::

            Possible warnings tba. 

        Docstring continued...

        .. note::

            The syntax should be ... 

        Parameters
        ----------
        value : list
            Array read from the parameter file
        key : str
            Name of the parameter

        """

Hi,

would it be possible to have the option of including the :type field during expansion of docstring?

I find the package very convenient. Would it be possible to extend the functionality to classes and modules?

The current implementation assumes that all the field lists are added together but that may not always be the case. Sometimes the field lists could be interspersed by ReST directives such as .. versionchanged or .. versionadded as in these examples

• https://github.com/zzzeek/alembic/blob/master/alembic/operations.py#L725-L731
• https://github.com/zzzeek/alembic/blob/master/alembic/operations.py#L747-L757

If a field description is more than 2 lines long and if the docstring is regenerated, only 1st two lines of the description are retained. This looks like a bug in the regex for parsing the fields section of the docstring.

It seems function annotations are not supported (https://www.python.org/dev/peps/pep-3107/) as M-x sphinx-doc does not work on the following code:

def get(self) -> dict:
    raise HTTPMethodNotAllowed()

As the title says: If type hints are used, sphinx-doc does not work anymore

E.g

def sum(a:int, b:int):
    return a+b

Just as the title shows.
spacemacs is a A community-driven Emacs distribution. It is very powerful.