Feature Request: recursive_paths should find src/ and include/ from the top level directory by default

[wroyca]

Poxy currently relies on the recursive_paths option to find the source files. Instead, it should look for src/ and include/ in the top-level directory of the project

# this is a config file for Poxy - a Doxygen + m.css front-end written in Python.
# https://github.com/marzer/poxy

name   = 'foo'
github = 'foo/foo'

[sources]
- recursive_paths = [ '../src' ]
extract_all = true

[marzer]

Instead, it should look for src/ and include/ in the top-level directory of the project

Sorry, but no it shouldn't. There's a lot of variation among C++ projects here so it simply doesn't make sense to build-in assumptions. Examples:

• Not all projects will ascribe the same meaning to src/
• Some use inc/ instead of include/
• Some will have internal sub-folders that should not be traversed

...and so on. It's one line in the config. I'm sure you'll manage.

Poxy currently relies on the recursive_paths option to find the source files.

There's also paths for non-recursive lookup.

[wroyca]

Instead, it should look for src/ and include/ in the top-level directory of the project

Sorry, but no it shouldn't. There's a lot of variation among C++ projects here so it simply doesn't make sense to build-in assumptions. Examples:

• Not all projects will ascribe the same meaning to src/
• Some use inc/ instead of include/
• Some will have internal sub-folders that should not be traversed

...and so on. It's one line in the config. I'm sure you'll manage.

Poxy currently relies on the recursive_paths option to find the source files.

There's also paths for non-recursive lookup.

I think there was a misunderstanding, I didn't meant to completely remove the option. Poxy is a documentation generator for C++, it would make sense for it to have a default fallback for the most common layout — you already have one for source_patterns. Naturally there would be unorthodox layouts, but recursive_paths would exist for exactly that.

Anyway, thanks for your reply, I appreciate your work with Poxy so far.👍

[marzer]

I think there was a misunderstanding, I didn't meant to completely remove the option.

Ah, indeed. That's exactly what I thought you were suggesting 😅

you already have one for source_patterns.

Yeah, that's true, though that wasn't based on any personal preference; it's based on the fact that C++ file extensions don't tend to vary very much. There's a very 'safe' pattern subset that can be reasonably applied to the vast majority or use-cases. The same can't be said for directory structure (at least not with the same level of safety/ubiquity).

Something else worth noting is that unlike regular Doxygen, Poxy treats all paths as being relative to poxy.toml, meaning the 'top-level' of the project here would simply be the folders sitting next to poxy.toml in the filesystem. Since the convention for documentation generation boilerplate in C++ is to have a docs subfolder (or similar), having some 'top-level' includes as a default would likely end up being useless for a very large majority of people (at best), or unexpectedly/accidentally include totally the wrong thing (at worst). I could try to encourage people to put poxy.toml in their repository root to combat this, but personally I think sequestering doxygen noise in a subfolder is the right move - our repo root folders are already busy enough with all the various build systems, package managers, .gitattributes, .gitignore, .editorconfig, et cetera...

Anyway, thanks for your reply, I appreciate your work with Poxy so far.👍

Thanks :)