1

I have a project structured like this.

OpenRGB-cppSDK
  doc
    Doxyfile
    main.md  -- Doxygen main page
  examples
    .cpp files with examples
  include
    public .hpp files
  src
    .hpp and .cpp files
  tools
    cli demo
README.md  -- github main page

Now i would like to create a clickable reference to the README.md file and examples directory from the main.md, but i cannot figure out how.

I've added the README.md and examples to the INPUT variable

INPUT                  = ../doc ../include ../src ../README.md ../examples

and i've verified that the FILE_PATTERNS include *.md.

However when i write a sentence into main.md like this

Basic examples are in the \ref README.md, more advanced examples in directory \ref examples.

doxygen tells me it was unable to resolve reference to README.md and examples, even though i can see in its output it found the files

Reading E:/Youda/Projects/OpenRGB-cppSDK/README.md...
Generating docs for page md_E__Youda_Projects_OpenRGB_cppSDK_README...
Preprocessing E:/Youda/Projects/OpenRGB-cppSDK/examples/ContinuouslyUpdateColors.cpp...
Parsing file E:/Youda/Projects/OpenRGB-cppSDK/examples/ContinuouslyUpdateColors.cpp...
...

In the generated web page it shows a button "Related pages" with entry "OpenRGB_cppSDK" that takes me to the README file enter image description here

but the reference to the README from main.md doesn't work.

I've also tried EXTRACT_ALL = YES, but then what happens is that the main.md page gets a clickable reference to README.md but when i click it, it takes me to a blank page that looks like this enter image description here

Please, what am i doing wrong?

Youda008
  • 1,788
  • 1
  • 17
  • 35

1 Answers1

1

The version with the markdown type of link does work: [Test with md type](../README.md)

The full project: README.md

# this is the readme file

this is the readme file

doc/main.md

# this is the main file

this is the main file


the test with \\ref no path: \ref README.md

the test with \\ref with path: \ref ../README.md


[Test with md type](../README.md)

doc/Doxyfile

QUIET=YES
INPUT                  = ../doc ../README.md

output in: doc/html/md_main.html

enter image description here

Why doesn't the \ref not work, from the documentation:

24.107 \ref <name> ["(text)"]

Creates a reference to a named section, subsection, page or anchor. For HTML documentation the reference command will generate a link to the section. For a section or subsection the title of the section will be used as the text of the link. For an anchor the optional text between quotes will be used or if no text is specified. For LATEX documentation the reference command will generate a section number for sections or the text followed by a page number if refers to an anchor.

The "../README.md" doesn't constitute a valid name The "README.md" would work when it is a local file (i.e. local to the doc directory).

albert
  • 8,285
  • 3
  • 19
  • 32
  • Thanks. But do you also know how to reference the directory? In the top panel i have a tab "Files" which shows the tree of files with a clickable directory entry that leads to a page with description i added with `/** \dir examples blabla */`, how to create a clickable link to this page? – Youda008 Jul 12 '21 at 18:05
  • I don't think there is a diect way to do it. Best is to place in the paragraph of the `\dir` a `\anchor` and reference this. – albert Jul 13 '21 at 07:39
  • Hm, that doesn't work, but thanks anyway. – Youda008 Jul 13 '21 at 09:08
  • What did you try in this respect? – albert Jul 13 '21 at 09:29
  • I did some tests as well and it looks like the `\dir` command is not seen as a command that creates a new page that needs local references (like e.g. the `\page` command does). – albert Jul 13 '21 at 10:03