54

I would like to add custom (non-project) files to generate some extra pages with Doxygen.

I am (was actually) unsure how these files should be named and how their content should be formatted.

albert
  • 8,285
  • 3
  • 19
  • 32
Veger
  • 37,240
  • 11
  • 105
  • 116

5 Answers5

54

I having been searching quite a lot before I found the answer, so I thought it would be nice to share!

According to this Doxygen gotchas article I finally found that: you need to add a file with the dox extension. Its content should contain C-style comment blocks:

/*!
  \page My test page
  contents
  ...
  more contents
*/

Make sure your custom files are placed in a directory which is included in INPUT setting or in the current directory if INPUT is left empty, so these files can be found.

albert
  • 8,285
  • 3
  • 19
  • 32
Veger
  • 37,240
  • 11
  • 105
  • 116
  • 2
    Markdown is now also available. [Here's](http://stackoverflow.com/a/9522667/339872) how to use it. – antitoxic Mar 13 '12 at 11:18
  • It will (at the time of writing) accept some other comment forms, e.g. `///` instead of C-style multiline comments and `@` instead of `\`, but it seems the last line must consist of the comment marker (`\\\`) and nothing else. – Pharap Aug 10 '19 at 13:20
44

Just for completeness: there are 3 possible extensions which doxygen treats as additional documentation files: .dox, .txt, and .doc.

Files which such extension are hidden from the file index. Inside the file you need to put one or more C/C++ style comment blocks.

doxygen
  • 14,341
  • 2
  • 43
  • 37
  • 22
    As this is still highly popular on google: It looks like nowadays, .md has to be added to that list. – Lukx Feb 03 '15 at 12:58
  • Using doxygen 1.8.13, .txt does not work. .md works for me. – Fabian May 05 '17 at 06:45
  • @Fabian See the tag EXTENSION_MAPPING in the doxygen configuration file(Doxyfile) – albert Jun 30 '18 at 11:33
  • @albert Thank you. This allows to add txt files, but then I need to choose a language to parse them in and use doxygen comments within the txt file. Markdown files are automatically treated as a doxygen page without modifying the md file, which is what I also expect for txt files. – Fabian Jul 11 '18 at 05:17
  • @Fabian, I think I understand your problem, in the documentation the possibility for Markdown has not been mentioned . You probably need: `EXTENSION_MAPPING = txt=md`. – albert Jul 11 '18 at 08:19
16

For even more completeness, starting with Doxygen version 1.8 (I believe), it now supports additional text files which are very similar to markdown syntax. You no longer need to use C/C++ style comment blocks. Instead, just write almost normal text and make sure that the text file is in the INPUT path, and that your doxygen scan actually looks for files with .markdown extension (or any other extension you choose to use, like .md).

DXM
  • 4,413
  • 1
  • 19
  • 29
  • I'm not positive (perhaps treat this as a question) but I don't see a way to add commands like \dot into a markdown document. – pedz Jan 26 '14 at 01:11
  • @pedz: It's been a while since I played around with Doxygen (switched jobs a while back), so don't remember all details. You can't add any custom tag into markdown. It has to be supported by the parser, but I believe "\dot" is a valid tag: http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmddot. so possibly a) you don't have the right version or b) in your config file you didn't specify that DOT tool is available. – DXM Jan 26 '14 at 02:55
11

For clarity:

In the .dox configuration file, add the file to the INPUT directive with something like this:

INPUT = ../src \
        ../include \
        ../docs/my-extra-file.txt

If the file had the appropriate extension, say like .h or .c then Doxygen would find the file without adding to the INPUT directive. Inside the file use normal Doxygen tags, as in the source, i.e. inside comment blocks, like:

/*! \mainpage MyProject - A Brief Description.
\image html Mylogo.png
\section my-intro MyProject Introduction
\htmlinclude about-MyProject.html
*/

One can also just use one of the include tags, like the "\htmlinclude" in the above example, any where in the code.

Veger
  • 37,240
  • 11
  • 105
  • 116
Wiley
  • 506
  • 5
  • 4
1

Just list your custom files in the INPUT macro in your doxyfile. You can choose whatever name you find appropriate. Format is text with Doxygen tags.

mouviciel
  • 66,855
  • 13
  • 106
  • 140
  • I tried that, but the file got included as a source file (added into list of files). Using the dox extension seems to prevent this – Veger Jun 16 '10 at 10:36