Automatically document directories by creating respective dox files

[wroyca]

Is your feature request related to a problem? Please describe.

Referring to https://github.com/marzer/poxy/issues/21#issuecomment-1449182509, "registering" documented files with Doxygen stands out as notably user-hostile, particularly when dealing with local installations. In short, with a local project structure, we must "describe" each directory from our source-tree, as these directories don't rely on relative paths. For example:

/// @dir C:/Users/wroy/Desktop
/// @brief a

/// @dir echo
/// @brief b

/// @dir echo/echo
/// @brief c

/// @file echo.hxx
/// @brief d

This doesn't transition effectively to CI or to another individual's computer. In such cases, they would need to modify "C:/Users/wroy/Desktop" to indicate the correct absolute path.

Describe the solution you'd like

During the generation phase, it might be advisable to automatically document directories (using path or recursive_path as context) by creating respective dox files with "@dir" and "@brief" annotations. If a user wishes to furnish directory description, then a manually created dox file should take precedence

Additional context

☕

[marzer]

oooooh that's a great idea, and likely quite easy to implement

[mosra]

This doesn't transition effectively to CI or to another individual's computer.

This seems to be a recurring issue that everyone suffers from which I myself never had a problem with. I've never needed to include the full path for the @dir or @file commands, never in the 15 years of working with Doxygen. There were insane bugs all over, but this was never a problem. So I'd like to understand what is it everyone else is doing differently that they run into this :D What are your INPUT, STRIP_FROM_PATH and STRIP_FROM_INC_PATH settings?

See also this comment.

[marzer]

What are your INPUT, STRIP_FROM_PATH and STRIP_FROM_INC_PATH settings?

@wroyca if you re-run poxy with --bug-report (now that I've fixed it), the generated Doxyfile will be in the zip at poxy_bug_report/temp

So I'd like to understand what is it everyone else is doing differently that they run into this :D

@mosra yeh now that you mention it I've never run into this either - I always just use a .dox file in the directories themselves with @dir / @brief and have never had any problems, so I am curious about this too O_o

[wroyca]

This doesn't transition effectively to CI or to another individual's computer.

This seems to be a recurring issue that everyone suffers from which I myself never had a problem with. I've never needed to include the full path for the @dir or @file commands, never in the 15 years of working with Doxygen. There were insane bugs all over, but this was never a problem. So I'd like to understand what is it everyone else is doing differently that they run into this :D What are your INPUT, STRIP_FROM_PATH and STRIP_FROM_INC_PATH settings?

See also this comment.

Here's a simple project structure:

hello.zip

And the respective doxygen, generated by poxy:

Doxyfile.zip

---

As observed, the path is an absolute one, not relative. In other words, we obtain /home/wroy/hello/, and in order for the files to become visible, we need to document /home/wroy/hello/, hello/hello/, and ultimately, hello/.

[mosra]

And I assume you want /home/wroy/hello stripped away, right?

The relevant Doxyfile parts are this:

STRIP_FROM_PATH        = "/tmp/poxy/bug_report/temp/pages"
STRIP_FROM_INC_PATH    =
INPUT                  = "/home/wroy/hello/hello" \
                         "/home/wroy/hello/libhello" \
                         "/tmp/poxy/bug_report/temp/pages"

Not sure what's the temp pages directory but it should be something like this instead, I think, then it wouldn't include the whole path in the file list. The project root is probably something the project configuration itself should specify, can't really automate that I think -- there's not really a way to know whether it's meant to be #include <libhello/hello.h> or just #include <hello.h>.

STRIP_FROM_PATH        = "/home/wroy/hello" \
                         "/tmp/poxy/bug_report/temp/pages"
STRIP_FROM_INC_PATH    = "/home/wroy/hello"
INPUT                  = "/home/wroy/hello/hello" \
                         "/home/wroy/hello/libhello" \
                         "/tmp/poxy/bug_report/temp/pages"

[marzer]

@wroyca In poxy-speak you need to use the strip_paths option in [sources], which is what becomes doxygen's STRIP_FROM_PATH.

Not sure what's the temp pages directory

That's an internal implementation detail of poxy - a folder for generating additional documentation files if necessary (e.g. the page for the Changelog). It's not surfaced to the user in any meaningful way (i.e. they don't need to take it into account when specifying paths).

[mosra]

Alright, thanks for clarifying :)

which is what becomes doxygen's STRIP_FROM_PATH.

So I assume it does basically what I suggested above, right? I wonder if this is where poxy automagic would help, i.e. setting the STRIP_FROM_*_PATH implicitly to something. Which might be possibly wrong (stripping too much), but in my opinion better than having C:/ or /home/whoever shown in the output :D

[wroyca]

And I assume you want /home/wroy/hello stripped away, right?

The relevant Doxyfile parts are this:

STRIP_FROM_PATH        = "/tmp/poxy/bug_report/temp/pages"
STRIP_FROM_INC_PATH    =
INPUT                  = "/home/wroy/hello/hello" \
                         "/home/wroy/hello/libhello" \
                         "/tmp/poxy/bug_report/temp/pages"

Not sure what's the temp pages directory but it should be something like this instead, I think, then it wouldn't include the whole path in the file list. The project root is probably something the project configuration itself should specify, can't really automate that I think -- there's not really a way to know whether it's meant to be #include <libhello/hello.h> or just #include <hello.h>.

STRIP_FROM_PATH        = "/home/wroy/hello" \
                         "/tmp/poxy/bug_report/temp/pages"
STRIP_FROM_INC_PATH    = "/home/wroy/hello"
INPUT                  = "/home/wroy/hello/hello" \
                         "/home/wroy/hello/libhello" \
                         "/tmp/poxy/bug_report/temp/pages"

Not quite, for that I can use strip_paths = [ '/home/wroy/hello' ] but even stripped, each path must still be specified explicitly in a dox with @dir and @brief annotations to show up in files.

Example:

$ pwd
/home/wroy/hello

$ cat <<EOF >> doc/poxy.toml
strip_paths = [ '/home/wroy/hello' ]
EOF

$ cat doc/poxy.toml
name = 'hello'
cpp = 17

[sources]
recursive_paths = [ '../hello', '../libhello' ]
patterns = [ '*.hxx', '*.ixx', '*.txx', '*.cxx' ]
extract_all = false # debug
strip_paths = [ '/home/wroy/hello/' ]

---

$ cat <<EOF > hello/hello.dox
/// @dir /home/wroy/hello
/// @brief a

/// @dir hello/hello
/// @brief b

/// @dir hello
/// brief c
EOF

$ cat hello/hello.dox
/// @dir /home/wroy/hello
/// @brief a

/// @dir hello/hello
/// @brief b

/// @dir hello
/// brief c

[marzer]

You don't need to specify a path using @dir - just the directive alone is sufficient, e.g. putting this in dir.dox at your source root:

/// @dir
/// @brief The root folder of all source files.

[marzer]

@mosra

So I assume it does basically what I suggested above, right? I wonder if this is where poxy automagic would help,

Yeh, pretty much. Maybe walking up the directory tree and looking for a .git folder would be a good default 'automagic' STRIP_FROM_PATHS, in the absence of any user-provided value?

[wroyca]

You don't need to specify a path using @dir - just the directive alone is sufficient, e.g. putting this in dir.dox at your source root:

/// @dir
/// @brief The root folder of all source files.

Only if you stripped /home/wroy/hello in poxy.toml in which case, it will work, but that's just a mitigation, and we're back to square one where we need to be explicit about /home/wroy/hello

For example, not stripping /home/wroy/hello and using a single @dir directive:

[marzer]

@wroyca I promise you you don't need to be explicit about paths at any point w.r.t. @dir, apart from the 'strip from' setting. You are doing something weird that isn't obvious to me.

[wroyca]

@wroyca I promise you you don't need to be explicit about paths at any point, apart from the 'strip from' setting. You are doing something weird that isn't obvious to me.

That's exactly my point \:), we need to be explicit about paths in 'strip from'

[marzer]

Well yes, but that's by design? You don't need to be explicit in your @dir annotations, so I dont understand what the issue is.

[marzer]

Like, you pretty much have to use strip_paths / STRIP_FROM_PATH. I should make it emit a warning in poxy when it's omitted, tbh.

Unless we want to get into guessing the project root, but that's orthogonal to the idea of autogenerating @dir entries.

[wroyca]

Well yes, but that's by design? You don't need to be explicit in your @dir annotations, so I dont understand what the issue is.

Both way are the same, that is to say:

/// @dir
/// @brief root 

with

strip_paths = [ '/home/wroy/hello' ]

is the same as

/// @dir /home/wroy/hello 
/// @brief a

/// @dir hello/hello
/// @brief b

/// @dir hello
/// @brief c

[marzer]

No, because you're still hard-coding absolute paths for some reason, which you don't need to do. See toml++'s config: https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml - not an absolute path in sight.

[wroyca]

No, because you're still hard-coding absolute paths for some reason, which you don't need to do. See toml++'s config: https://github.com/marzer/tomlplusplus/blob/master/docs/poxy.toml - not an absolute path in sight.

Ah! our miscommunication stem from "strip_paths" where I interpret "strip_paths" as what to strip from the path, that is to say, explicitly. But now I found out what you can just pass a relative path and it will "strip" the path leading up to it. Now it make sense ~

[mosra]

Yeah, that's the problem, you're using absolute paths. Don't use them. Anywhere. If everything is relative to the Doxyfile, the INPUT, the STRIP_FROM_PATH, etc., then it works.

[wroyca]

Yeah, that's the problem, you're using absolute paths. Don't use them. Anywhere. If everything is relative to the Doxyfile, the INPUT, the STRIP_FROM_PATH, etc., then it works.

Indeed - I guess that a significant number of individuals, similar to myself, wouldn't anticipate strip_paths to accommodate a relative path :sweat_smile:

[marzer]

Hmmmn, maybe I should add a note to the config wiki page. So to clarify: anywhere you can specify a path in poxy, regardless of what it's for, is assumed to be relative to poxy.toml, unless you explicitly put in an absolute path.

[wroyca]

Closing as this was mostly due to me misunderstanding how things work. :)