search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Allow for C arguments to be labelled as "Parameters" or "Arguments" #12806

Open torressa opened 2 months ago

torressa commented 2 months ago

Describe the solution you'd like The easiest solution would be to split arg and argument to a Parameters label with a new TypedField

https://github.com/sphinx-doc/sphinx/blob/0504903d47b70afd1e89d4e5a15ae131156c7569/sphinx/domains/c/__init__.py#L297-L308

Describe alternatives you've considered Or toggle the label with a flag somehow.

Happy to open a PR if this looks like a viable solution and of course for alternative solutions.

electric-coder commented 2 months ago

Can you remind us of the difference between arguments and parameters and how the current options aren't adequate for C?

torressa commented 2 months ago

It's just the label shown in the documentation. There's a distinction between arguments and parameters in C and some developers prefer the former label when writing their documentation. Currently, only the "Parameters" label can be used.

electric-coder commented 2 months ago

@torressa I don't have Brian Kernighan and Dennis Ritchie's The C Programming Language on hand, but for a definition we can mention Stack Overflow's canonical: What's the difference between an argument and a parameter?

It's just the label shown in the documentation.

Would it be a viable alternative to use .. c:alias:: name? A similar request was made for Python #7609

torressa commented 2 months ago

Would it be a viable alternative to use .. c:alias:: name? A similar request was made for Python https://github.com/sphinx-doc/sphinx/issues/7609

I'm not sure, I tried replacing a function :arg arguments with an alternative declaration. It's a bit messy and doesn't look the same when rendered:

.. c:function:: int foo(Bar *bar)

   This is my foo function description

Need a new line

   Arguments

   .. c:var:: Bar *bar

      This is what bar is

Maybe there's a better way but this renders very different to the standard and more concise:

.. c:function:: int foo(Bar *bar)

   This is my foo function description

   :arg bar: This is what bar is

Could we not add an option for a function that allows for this switch (similar to :single-line-parameter-list:)? This way we don't have to change the source for this small change

torressa commented 2 months ago

We found a solution by overriding the CDomain and replacing the function directive. I think this is still nice to have