search

Feneric / doxypypy

A more Pythonic version of doxypy, a Doxygen filter for Python.
GNU General Public License v2.0
149 stars 49 forks source link

Fix the handling of module-level namespaces. #49

Open robottwo opened 6 years ago

robottwo commented 6 years ago

Addresses issue #33.

The main part of this patch is to auto-detect the top level namespace for a given python file. It does this by walking up the directory tree and scanning for init files until it locates the top-most one.

This patch also fixes the parsing filter so that it automatically applies the correct top-level namespace when run on module files by default. This means no more havingt o put @namespace comments at the top level of modules. It also suppresses using the @namespace tag in class definitions, which confuses doxygen into thinking that classes are namespaces. That's no longer neccessary anyway because of the module-level namespace.

With this patch, doxypypy produces much better output by default when run on complex module codebases. There are added options to suppress the new behavior and get the old behavior back, for those who don't want namespaces in their documentation (although I can't imagine why one would want that).

Note that, while it wasn't the original intent, this patch also makes doxypypy very useful to creating unified documentation sites -- you can point it at multiple python modules (in a single doxygen config), and it will create a structured documentation site combining all of them, organized by namespace. This is a neat trick for organizations to consolidate internal code documentation in a single location.

wich commented 6 years ago

This is a very desirable feature and works beautifully. Can this please be integrated?

Feneric commented 6 years ago

I'd be happy to add this, but we need some tests for it. All the major features of doxypypy are presently covered by tests in the test folder, and all of these tests get run prior to each release. We don't want to go down the path of adding in new features that'll silently break later, because that won't help anybody.

buhtz commented 2 years ago

@robottwo Can you give us a statement about the missing tests please.

robottwo commented 2 years ago

Sorry, I haven't touched this code in 4+ years. As I recall, it's not clear to me how to write a useful unit test for this particular feature, since the new behavior is a subjective change in the output rendering.

buhtz commented 2 years ago

Thanks for your feedback. For me it would be absolute fine if a contributor is not able to know how to write unittests.

@Feneric To honor the work of @robottwo and don't throw it into the trashcan unittests should be written.

One can not presume that each contributor is able to write unittests or even know why this is mandatory.

Feneric commented 2 years ago

@Feneric To honor the work of @robottwo and don't throw it into the trashcan unittests should be written.

You're welcome to write them. My free time is limited, and it's not a huge ask for folks to provide tests that demonstrate that their changes actually work. A lot of people use doxypypy and value its stability. Merging untested changes risks that stability and would potentially break it for other users. I do try to add tests to submitted changes that weren't provided with them over time, but if it wasn't a priority of the submitter to even provide basic certification that their changes work it's not clear to me why it should be higher on my priority list than it was on theirs. My throughput on adding such tests and merging such work is thus quite slow.