Feature request: `See also:` section

[aherrmann]

Hi,

I recently gave doxypypy a try and noticed, that See also: sections are ignored. Doxygen has a @sa command that will render a See also section with links to the mentioned functions. Could you please add this section to doxypypy? In my mind it should support the following syntax.

See also:
    function_a
    member_b

Maybe also the following.

See also:
    function_a, member_b

And produce the following output, or similar.

@sa function_a
@sa member_b

It's worth mentioning, that doxygen can take some hints on automatic link generation.

What do you think about this?

Best,

Andy

[Feneric]

I don't have anything against the idea, but do note that the intent of the project is to make it easy to use "normal" Python with Doxygen more than it is to make every Doxygen feature be usable in a more Pythonic way. For example, I think the @dot and @msc features are really cool, but no one really uses them in typical Python code so I'm not going out of my way to add them to doxypypy. "See Also:" is possibly more widely used in the general Python community though, so I'll definitely consider it, especially if others chime in asking for it.

[aherrmann]

Thanks for considering.

I agree, that there's probably not much use for things like @dot, or @msc in doxypypy.

But, as you point out, "See also" is a fairly commonly used pattern. See, e.g. the numpy documentation which is littered with these.

It's a slightly different issue, but somewhat related. I have a docstring in which I'm referring to a website that inspired that function, and provides a useful resource to understand the function better. It looks something like this:

Credits:
    Refer to awesome article by that guy [1].

    [1]: www.some-page.com/some/resource

The link is actually correctly interpreted by doxygen. However, the Credits: part is in normal font, and the newline is ignored. Now, as you pointed out, it's certainly not necessary to try and recognize all kinds of specialized sections. But, maybe it would help to recognize section headings in general and just boldify them. I.e. @b, like you do with the examples section. It's just a thought. I'd be curious what you think of that idea.

[Feneric]

Yeah, actually I think I'm more in favor of the generic bolding of apparent titles than even the "See Also:". The trick with that though is to avoid false positives, so it may be that we'd have to require an initial capital letter and only match single words. We'd have to go through the existing docstring parser state machine as well and possibly reorder some things as we wouldn't want it matching one of our existing headings that already has a special meaning.

[aherrmann]

The @sa checks every word for automatic link generation.

I.e. in the following situation

def func_a():
"""function a

@sa func_b
"""
pass

def func_b():
"""function b

@sa func_a
"""
pass

Doxygen will create a clickable link to the documentation of func_a in func_b and vice versa. However, if you don't use @sa you have to be more explicit and write func_a() to trigger automatic link generation. For members this get's a bit more tricky, since you can't use parenthesis on them.

See Also: breaks the one word only pattern. And, the contents should be displayed in some sort of list, similar to the Args: list, rather then a block paragraph. It seems to me that See Also doesn't fit in a general section pattern.

I understand, that you don't want to litter doxypypy with all kinds of special commands. But, I think See Also: is a sufficiently common pattern to be worth a special treatment. And it is very similar to e.g. the Args: list. So, I guess it shouldn't be too difficult to implement.

However, a general section would be nice to have as well. I guess the @par command could be useful for that. But that seems to be far more difficult to implement properly.

[Feneric]

The generic section headers are in there now. I'm still thinking about whether or not "See Also" can be done cleanly by piggy-backing it off of exceptions.

[Feneric]

OK, "See Also" is in there now too, so please give it a try.

[aherrmann]

Hi,

Thank you very much! The "See Also" section works, and the general section also seems to work. The "Credits:" are boldified, but the links ([link]: www.url.com) survive it. That's very good.

There are two cosmetical details.

First, Doxygen sections (e.g. Parameters, or Returns) don't carry a colon. The boldified section title does carry a colon. Could doxypypy remove the colon to make them match?

Second, the body text of the section continues in the same line as the section heading if it is not a list of some sort. The only solution I found to that would be to use the @par command. E.g. transform this

Section:
    Paragraph one.

    Paragraph two.

Into this

@par Section
    Paragraph one.
@par
    Paragraph two.

How hard would it be to detect a second, (or more) paragraph of a section? If it's not hard, this might be an easy solution.

Best,

Andy

[Feneric]

Thanks for the test cases.

The colon is probably an easy fix, the paragraph marker less so. I'll have to look though; no promises on either until I think through it a bit.

[Feneric]

The colon stripping is active now.

[Feneric]

OK, I believe it now has the paragraph markers in place. Please let me know if it works properly for you.

[aherrmann]

Thanks for the changes.

I think there are still some issues, though.

E.g. the following docstring:

Section:
    Some paragraph.
    With a second line.

    And a second paragraph.
    With a second line.

Section:
    Some paragraph.
    With a second line.

    And a second paragraph.
    With a second line.

Not part of the section.
Second line not part of the section.

Yields the following doxygen code:

# @b     Section:
#        Some paragraph.
#        With a second line.
# @par
#        And a second paragraph.
#        With a second line.
# @par
# @b     Section:
#        Some paragraph.
#        With a second line.
# @par
#        And a second paragraph.
#        With a second line.
# @par
#    Not part of the section.
#    Second line not part of the section.

The resulting html doc looks like this:

As you can see, the heading is not really a true heading. And the second section heading becomes part of the former section.

The following doxygen code however:

#    @par Section
#        Some paragraph.
#        With a second line.
#    @par
#        And a second paragraph.
#        With a second line.
#
#    @par Section
#        Some paragraph.
#        With a second line.
#    @par
#        And a second paragraph.
#        With a second line.
#
#    Not part of the section.
#    Second line not part of the section.

Gives this result:

I'm also not sure, if it is a good idea to put everything into a @par. E.g. the first paragraph after @brief, imho looks better without. As I read the doxygen documentation it's really intended for sections. Not for the normal text.

So, I think @par is a good tool for the general sections. I think you could even use it for the Example section. But, if it's not a section then Doxygen's default handling will work just fine, I think.

I guess indentation would probably be a good criterion for whether to use @par or not.

What do you think?

[Feneric]

You can try now. We're getting close to the limit of what we can do with this approach without doing a pretty significant redesign over the docstring parser.

[Feneric]

Looks good, I've gone through all the changes and merged it in. I think we'll have to be a bit careful though about going much farther in this particular direction. I don't think we want to reinvent structured text (although incorporating an existing structured text parser on docstrings may make sense down the road if there's enough interest).

[aherrmann]

Thanks for merging.

I agree about the structured text part. The thought occurred to me, that it might be nice to have something like Markdown working inside. However, one should to be careful with this kind of thing since it's intended as a simple python connection to doxygen that supports different commenting styles like pep-8, or google.

I think for now I'll see how far I can get with the current state.

[Feneric]

Right, I think we're in agreement there.