sphinx
sphinx copied to clipboard
Ability to disable capitalisation on field names.
I would like to use field lists to describe function parameters in my library's documentation. Unfortunately the first character in the field name is automatically capitalised, which makes it not ideal for documenting parameters.
e.g. a list written as:
:bg: The background asset to use.
:palId: The location to which the palette will be copied.
is rendered as:
Bg The background asset to use. PalId The location to which the palette will be copied.
Digging into the code, it seems like the behaviour is hardcoded in sphinx/util/docfields.py
.
This behaviour is not present in docutils, and I think my use-case is valid based on their description: "Field lists may also be used as generic two-column table constructs in documents." (quickref)
Would a patch be accepted that adds an option to conf.py
which makes it possible to disable this behaviour?
Thanks!
This appears to be an autodoc
question. Indeed there is no capitalization when not in a docstring.
where the screenshot was using
'classic'
theme and this index.rst
Welcome to FOO's documentation!
===============================
Hello
:bg: The background asset to use.
:palId: The location to which the palette will be copied.
.. automodule:: test
:members:
and test.py
:
def foo():
"""For testing purposes
:bg: The background asset to use.
:palId: The location to which the palette will be copied.
"""
pass
Edit: but as you already found out it is https://github.com/sphinx-doc/sphinx/blob/59056aa7816ebae81aa6842290aa7a6ece14d1bd/sphinx/util/docfields.py#L276-L284 which is the cause.