Exclude static functions from c:autodoc

[RastislavTuranyi]

Hi! I have been testing out hawkmoth for a new C library (it's great that it allows me to use the full features of sphinx in C!), but I have been surprised to find that the c:autodoc directive pulls everything into the docs, including static members (e.g. static functions), which is unlike the default sphinx automodule that by default ignores private members. As far as I can see, there is no way to control this behaviour in hawkmoth, unless I missed something?

If not, I wanted to ask whether you have considered adding control options to c:autodoc? I particularly would appreciate the ability to exclude static members, maybe via an option like :exclude-static-members: which would effectively function as the opposite of sphinx :private-members:. If this is of interest to you, I would be interested in helping out with this!

[jnikula]

Thanks for the report!

I'm open to adding filtering like this. Just need to be careful about the implementation. To achieve what I think you want, I don't think it's purely about static. Also types and macros in a .c file should probably remain internal, right? But in a .h file it's the opposite. And with that, I'm not sure if "static" is the right word to use.

#166 is somewhat related.

[RastislavTuranyi]

I did not think of that! However, you are right in that the goal is to keep the documentation next to the code while creating sphinx docs only for the public interface. That said, I'm not sure it's a good idea to do this automatically based on whether the path is a .c or .h file - my instinct would be to use an option and leave the choice to the user - but I'm still learning C so I'll defer to you on that!

Nevertheless, when talking about options, maybe calling the all-in-one option :exclude-private-members: could work? It's similar to autodoc naming, but not sure whether it clashes with any C nomenclature. On the other hand, do you think it would be beneficial to separate this exclusion/inclusion behaviour into separate options? E.g. :exclude-static-members:, :exclude-macros:, etc. It would give more fine-grained control at the cost of greater complexity.

[jnikula]

I explicitly do not want to add a ton of options. It should be fairly simple, both to implement and use. If you want the extra level of fine grained control, then you should use the more fine grained directives for each individual symbol. Many people want to use them anyway just to create a better narrative ordering for the documentation than what the order in the source file is.