Doxygen: how to make an entire file "Internal"?

Question

I want to make an entire page of my documentation 'Internal' so that it is only generated when INTERNAL_DOCS = YES. I'm using markdown format for the bulk text of this document, so all these files are .md extension, not that that should make a difference.

If I apply this within an @page part of a source text file the following works as expected, in that all evidence of the page disappears from the output:

@internal
@page hidden_page Blah Blah
Text is here.    
@endinternal

However, some of my pages are quite long and I've factored them out to a separate file.

# Page Title

Extensive text here.

The first-line markdown title stops Doxygen using the filename for the title of the page.

The problem is, if I do this...

@internal
# Page Title

Extensive text here.
@endinternal

The text body is duly hidden, but the (blank) page still exists in the output, showing the filename as the page title.

Reversing the order of the top lines makes no real difference - it just means the blank page is titled differently.

I can't find anything in the relevant parts of the Doxygen manual. I'm using 1.8.5.

One, undesirable, solution is to 'unfactor' the separated page(s) back into a page that is always visible and use the technique described at the top. However, there are quite a number of such pages.

Does anyone know how whole files can be made completely internal, or have any other approaches that may work for this?

Answer 1

I've not had a lot of success with using @internal where pages are concerned so the method I have had success with is using @if along with ENABLED_SECTIONS, see Doxygen if command. I've tested the following out with python files and although this does generate a couple of warnings it does what I think you need.

## @if COND1
# @file cond_file.py Conditional File
#
# Conditional documentation.
#
# @page conditional_page Conditional Page
#
# This page will only exist if COND1 is set.
#
# @endif

The if you want the section included in your documentation simply add the following to the doxygen config file:

ENABLED_SECTIONS = COND1