sphinx-apidoc cannot understand var and type args in one line. How to fix this?

Question

I am using sphinx reSt to write docstrings for functions and I have created a mustache setting to customize docstring automatic generation in VsCode as below:

{{! Sphinx Docstring Template }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#args}}
:param {{var}} {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
:param {{var}} {{typePlaceholder}}{{#default}}, optional defaults to {{/default}}{{&default}}: {{descriptionPlaceholder}}
{{/kwargs}}
{{#exceptionsExist}}

{{#exceptions}}
:raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#yieldsExist}}

{{#yields}}
:yield {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/yields}}
{{/yieldsExist}}
{{#returnsExist}}

{{#returns}}
:return {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/returns}}
{{/returnsExist}}

For example:

# myproject/src/foo.py

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """my summary
     
    my extended_summary
     
    :param arg1 int: arg1 my description
    :param arg2 int: arg2 my description
    :param arg3 str Default "some_text": arg3 my description
     
    :return tuple[str, str, str]: return my description
    """
 
    return "a", "b", "c"

Now I am going to use sphinx-apidoc for generating documentation

I do sphinx-quickstart in myproject/docs. Then I run sphinx-apidoc -o ./docs/_modules ./src and then change directory to docs and run make html

However, the documentation that gets generated for me is as below:

If I modify the function's docstring to the standard format as below:

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """my summary
     
    my extended_summary

    :param arg1: arg1 my description
    :type arg1: int
    :param arg2: arg2 my description
    :type arg2: int
    :param arg3: arg3 my description, defaults to "some_text"
    :type arg3: str, optional
    :return: return my description
    :rtype: tuple[str, str, str]
    """

    return "a", "b", "c"

The the correct documentation gets generated.

As the template I have created for docstring is an standard alternative, how can adjust sphinx-apidoc to use my mustache template and generate correct documentation?

**Summery:

I have customized autodoc extension with mustache
I need sphinx-apidoc to understand the generated docstrings correctly**

sphinx-apidoc does not interpret docstrings. It's the autodoc extension (used when running sphinx-build) that does that. — mzjn, Jan 21 '22 at 16:36
I don't know what you mean. sphinx-apidoc just generates RST files with `automodule` directives in them. — mzjn, Jan 21 '22 at 16:40
@mzn please check my answer and also provide more explanation for your comment please — Amin Ba, Jan 21 '22 at 16:56
Well, I'm just pointing out facts. IMHO, it would be better to not mention Mustache at all and just focus on the differences between the docstrings. The type should come before the name of the parameter. `:param int arg1: description` is correct, `:param arg1 int: description` is not correct. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists. — mzjn, Jan 21 '22 at 17:03

score 0 · Answer 1 · answered Jan 21 '22 at 16:55

0

I think @mzn' comment is the real answer to this question.

Btw, the usual way to customize the output from sphinx-apidoc is to use Jinja templates. See https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-0

Anyway, I modified mustache file and I am getting the result I expect:

{{! Sphinx Docstring Template }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#args}}
:param {{typePlaceholder}} {{var}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
:param {{typePlaceholder}}{{#default}}, optional {{var}}: {{descriptionPlaceholder}}, defaults to {{/default}}{{&default}}
{{/kwargs}}
{{#exceptionsExist}}

{{#exceptions}}
:raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#yieldsExist}}

{{#yields}}
:yield {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/yields}}
{{/yieldsExist}}
{{#returnsExist}}

{{#returns}}
:return: {{descriptionPlaceholder}}
:rtype: {{typePlaceholder}}
{{/returns}}
{{/returnsExist}}

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """summary
    
    extended_summary
    
    :param int arg1: description
    :param int arg2: description
    :param str, optional arg3: description, defaults to "some_text"
    
    :return: description
    :rtype: tuple[str, str, str]
    """
 
    return "a", "b", "c"

answered Jan 21 '22 at 16:55

Amin Ba

1,603
1
13
38

You should not compare sphinx-apidoc and the way you use Mustache. sphinx-apidoc generates RST files with `automodule` directives. Your Mustache template generates docstrings. These are two different things. – mzjn Jan 21 '22 at 17:26
I changed mustache to make it compatible with sphinx-apidoc default expectation – Amin Ba Jan 21 '22 at 17:37
One of its expectation, as an example, is what you mentioned: `:param int arg1: description is correct, :param arg1 int: description is not correct.` – Amin Ba Jan 21 '22 at 17:45
And it is generating what I need, after this change – Amin Ba Jan 21 '22 at 17:46
You are conflating **sphinx-build** (called when you run "make hml") and **sphinx-apidoc**. https://www.sphinx-doc.org/en/master/man/sphinx-build.html, https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html – mzjn Jan 21 '22 at 17:48
I guess so. I am new to it. Anyway, when I click on Source, it is not showing the source. Do you have any idea why is that? – Amin Ba Jan 21 '22 at 17:55
1

Not sure. Have you enabled https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html? But if you have a problem with that, it is a topic for a new question. – mzjn Jan 21 '22 at 18:00
Btw, I'm sorry if I came across as a nag. I am glad that your problem is solved (but it had nothing to do with sphinx-apidoc). – mzjn Jan 21 '22 at 18:18
I am writing my second question as you advised. Please dont go and answer that one as well. Will share the link here :D – Amin Ba Jan 21 '22 at 18:22
https://stackoverflow.com/questions/70806046/how-can-i-make-sphinx-apidoc-show-the-source-code – Amin Ba Jan 21 '22 at 18:31

sphinx-apidoc cannot understand var and type args in one line. How to fix this?

1 Answers1