I include markdown files in my groups in doxygen like so:
/**
* #addtogroup foobar "Foo Bar"
* #{
* #subpage doc_foo_bar
*/
And they show up in the module documentation as requested. But anyways, they show up as normal top-level-pages, like so:
project
- foo_bar <-- The "doc_foo_bar" custom markdown page
- modules
- - foobar <-- The module "foobar", which includes a "detailed documentation", which links to the markdown page
How to remove the top-level markdown page if it is already included in the module documentation group?
I hope my explanation is plain.
Related
I would like to customise the appearance of the navigation tree column to have subpages' title nested inside the section's title they are referenced in. For instance, this simple example
/**
* #mainpage Mainpage
* #section section_1 Section 1
* Description of section 1
*
* #section section_2 Section 2
* Section 2 is composed of the following modules:
* - #subpage module_1_page
* - #subpage module_2_page
*/
/**
* #page module_1_page Module 1
* Module 1 description
*/
/**
* #page module_2_page Module 2
* Module 2 description
*/
results in the following output:
What I would like to achieve is something like this (I manually edited the HTML result):
I had a look at the page Customizing the output of the Doxygen documentation, but I was not able to find anything that seems helpful in this case.
Also, I had a look at grouping as an alternative to pages, but it does not really fit my purposes - I use groups for actual APIs documentation, whereas I'd like to use pages for more "descriptive" documentation.
Is this possible to achieve? For the sake of completeness, I am using doxygen v1.8.13.
Within a C project, I have to document code in dedicated .dox files and not n the C file themselves.
Excerpt from a .dox file:
/*! \page intro2 Introduction2
Sample text
\fn void foo(void)
#brief foo
foo does nothing.
*/
The documentation will appear in the "file list" under the foo.h file where my function is defined. My page will only display the "Sample text" line.
Is there any way to get the documentation in the page itself, after the "Sample text" line?
I know I can achieve that with groups. But because groups and pages are not managed the same way by Doxygen, I'd prefer getting the doc in \page.
Thanks,
/*! \page intro2 Introduction2
Sample text
foo
foo does nothing.
*/
.h For foo
\fn void foo(void)
#brief foo
Not exactly what you want but I'm thinking it will all go in a page now with link that you can click to read about the function. You might also be able to try to use \copydoc if you really want the documentation to be in the page.
I am trying to display values stored in Doxygen configuration variables. A simple example is the "PROJECT_NAME" variable in the standard Doxyfile configuration file. How can I display this at an arbitrary location in the code?
I've set up a file called main.dox with the following contents:
/*! \mainpage Main Page
- #PROJECT_NAME
- #PROJECT_NAME
- $PROJECT_NAME
- ${PROJECT_NAME}
*/
The value for PROJECT_NAME is set to "MY DOCS" in the standard Doxyfile configuration. The title displays correctly at the top of the documentation. On the main page, however, the code above generates the following:
*
*
* $PROJECT_NAME
* ${PROJECT_NAME}
How can I get it to display MY DOCS in the generated output?
You don't. Doxygen has no way to inject the text of configuration variables into arbitrary points in the code.
You can however write a custom command, an alias/macro that can be used to repeat text in various location. Granted, you'll have to repeat the text of your project name, but it'll be repeated in the configuration file:
PROJECT_NAME = Project Name
ALIASES += projname="Project Name"
In your documentation comments, you can now use \projname or #projname.
While documenting a project with Doxygen, I encountered the following problem.
I have a set of example programs (demo_1.c, demo_2.c,...) which reside inside the EXAMPLE_PATH set in the Doxyfile. I created a file examples.c with the following content to include the examples:
/**
* \example demo_1.c
* \example demo_2.c
* ...
*/
After running Doxygen, an Examples page is created within the navigation as I want it but the Examples section always looks like:
Examples
--------
Here is a list of all examples:
* demo_1.c
* demo_2.c
How can I change this page? I especially want to replace the text "Here is a list of all examples:" with a larger introduction.
I already generated the doxygen layout file and the header/footer files but this does not give me any useful information.
The solution is to create a DoxygenLayout.xml file and customize it with the information you want to appear on the examples page.
Doxygen will produce a template XML file, in the current directory, from the configuration it is using currently via the following command line:
$ doxygen -l
Point Doxygen to this file by editing the Doxyfile configuration file or using the Doxywizard GUI (Expert tab -> Build -> LAYOUT_FILE) to change the LAYOUT_FILE path to your new DoxygenLayout.xml file.
I recommend doing this step explicitly instead of relying on the default behavior to pickup the DoxygenLayout.xml when it exists in the folder Doxygen is run from.
You will need to edit the <tab type="examples"> XML tag and change the existing title attribute and add an intro attribute to suit your needs. The title attribute changes both the name of the header on the page and the TAB name across the top of the HTML browser so something shorter is better.
For example:
<tab type="examples" visible="yes" title="ALI Library Examples" intro="Welcome to the fantastic set of examples I have prepared for your enjoyment."/>
Produces:
ALI Library Examples
Welcome to the fantastic set of examples I have prepared for your enjoyment.
csv-simple.tcl
Note that I could not find any information about the intro attribute in the formal Doxygen documentation. I noticed it while reading the article Adding new user Tab in the Doxygen Layout.
I would like to consolidate documentation fragments on one page.
My use case is I have two different source modules where I want to put a doxygen fragment. Then in a third source module I want to put a #page that references the fragments.
My hope is that when the doc is generated I will see those 5 fragments consolidated onto one .html page.
The page/subpage system does not work because that just puts links on a page to the documentation fragments. I want the fragments consolidated onto one page.
This is the first .c file:
/*! #setfrag FRAG1
** this is some text for fragment 1
*/
This is a second file:
/*! #setfrag FRAG2
** This is some text for fragment 2.
*/
This is a third file:
/*! #page SOMEPAGE Page demonstrates consolidating fragments.
** #getfrag FRAG1
** #getfrag FRAG2
*/
I'm not sure if I understood your question right, but this should be exactly what grouping does. You can define a "group" using the tag #defgroup groupname description and then add the fragments to the group using the tag #addtogroup groupname.
Then you would define your group in any file (e.g. you could create a seperate file "groups.dox"):
/**
* #defgroup myGroup My Group
* #brief A brief description of \"My Group\"
* #details A more detailed description of \"My Group\".
*/
Them you can add fragments or complete files to this group by adding the following to the files:
/**
* #addtogroup myGroup
* #{
*/
// any contents you want to add to the group
/**
* #}
*/
This results in a tab called "Modules" where each group is listed as a "Module" with its own page. If you want to add the whole file documentation to the group ensure that you also enclose the #file tag with the #{ and #} tags.