doxygen

How to document the working/root directory in Doxgen?


In Doxygen one can use the \dir command to document directories. I often create README.md files in directories containing

\dir .
\brief Dir contains code (may contain bugs)

But how to write a documentation entry for the root directory of the project?

I have tried a file /README.md with the commands as shown above. As alternative /misc/README.md with \dir .. Both did not create a documentation entry for the directory itself.

I don't want to use absolute paths as the command's argument as this would not be portable.

example

This is a minimal example:

doxygen_root_directory_test/
├── dir_a
│   ├── a.h
│   └── README.md
├── Doxyfile
├── README.md
└── r.h

The *.h files are empty.

In this case the "root directory" is doxygen_root_directory_test. I execute doxygen from within that directory:

~/doxygen_root_directory_test$ doxygen -q
~/doxygen_root_directory_test/README.md:1: warning: No matching directory found for command \dir ~/doxygen_root_directory_test/

Note that I have replaced the path to the parent directory of the root directory with ~.

I am using doxygen version 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca).

output

Within the 'File List' (html/files.html) I would expect an entry for the root directory (. or "root" or ... 🤷). Similar to the one for dir_a:

screenshot of 'File List'

Also an equivalent to the directory reference for dir_a:

screenshot of 'dir_a Directory Reference'

How can I get directory reference entries for the root directory? As for dir_a above. Without writing absolute paths in the files.


Solution

  • Configure STRIP_FROM_PATH = ... Then one can document the root directory using

    \dir .
    

    In an input file within the root directory.

    This answer is based on albert's comment.