Override function declaration in autodoc for sphinx

by

You have a module-level variable that is used as the default value of a keyword argument in a function. Sphinx displays the value (instead of the name) of that variable in the function signature. This problem is discussed in another question, and the OP has also submitted an issue ticket at GitHub about it.

However, you can work around this in two ways:

  1. Override the signature in the .rst file by using autofunction, as explained in the answer to the linked question.

  2. If the first line of the docstring looks like a signature and if the autodoc_docstring_signature configuration variable is set to True (which it is by default), then Sphinx will use that line as the signature.

    So if you have a docstring that looks as follows,

    def myfunc(val=foobar):
    '''myfunc(val=foobar)

    Blah blah blah'''
    pass

    it should work in the way you want it.

    In the question, you have this first line in the docstring:

    .. function:: my_module.myfunc(val=foobar)

    This does not work because it does not look like a proper signature.

More Related Contents:

  1. Sphinx’s autodoc’s automodule having apparently no effect
  2. Sphinx autodoc is not automatic enough
  3. Sphinx cannot find my python files. Says ‘no module named …’
  4. Automatically document all modules recursively with Sphinx autodoc
  5. sphinx-build fail – autodoc can’t import/find module
  6. sphinx.ext.autodoc: Keeping names of constants in signature
  7. How would I cross-reference a function generated by autodoc in Sphinx?
  8. How do I create multiline comments in Python?
  9. What are the most common Python docstring formats? [closed]
  10. What does % do to strings in Python?
  11. pandas resample documentation
  12. How do I document classes without the module name?
  13. Inherit docstrings in Python class inheritance
  14. Can sphinx link to documents that are not located in directories below the root document?
  15. How do I document classes imported from other modules – hence without the declaration module’s name?
  16. How to add custom css file to Sphinx?
  17. Using javadoc for Python documentation [closed]
  18. How do I output a config value in a Sphinx .rst file?
  19. Keeping the API updated in Sphinx
  20. How to preserve line breaks when generating python docs using sphinx
  21. How to force Sphinx to use Python 3.x interpreter
  22. How to document Python packages using Sphinx
  23. Why do Python function docs include the comma after the bracket for optional args?
  24. How to use sphinx automodule and exposed functions in __init__
  25. Customize sphinxdoc theme
  26. How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?
  27. How do I sort this list in Python 3? [duplicate]
  28. sys.argv[1] meaning in script
  29. Python Requests and persistent sessions
  30. Python – Extracting and Saving Video Frames

Leave a Comment