I use some external libraries in my project, e.g. libev.
I realize I can use markdown (or href) and put
[libev](http://software.schmorp.de/pkg/libev.html)
in my document.
However that only works in a single place, and I don't want to have to put that in the dozens of places I refer to libev.
If it's "ClientWatcher" (one of my classes), doxygen auto links to the class.
Is there some way to tell doxygen to make all occurrences of the word "libev" auto link to http://software.schmorp.de/pkg/libev.html (for example)
If you add
ALIASES += libev="libev"
to Doxygen's configuration file you can use the \libev command to generate a link, like so
/** #mainpage
* See \libev for more info.
*/
Related
I have some source code (STM32 Peripherial Lib) with existing doxygen parameters which my Doxygen Builds without Problems.
For my project I want to generate a document with all functions in each file and a specific information which I want to add to the functions. But I want to keep the old informations for another doxygen configuration.
Is that possible?
I already added this for testing:
\ifnot "SECTION_DEFINE"
<normal Doxygen Parameters from original Source Code>
\elsif "SECTION_DEFINE"
#brief Function Check TODO
\endif
With this I could deactivate the existing documentation, but I need to write this \ifnot \elsif \endif to every function.
Can I just declare a Tag and only generate the documentation for this specific tag?
Kind regards
Andi
You may create a "related page" where only your additional information will be displayed with the \xrefitem command. As \xrefitem will also create a special text section within your original documentation you may want to combine it with your original idea of using section labels and conditional documentation. To top this concept off, use aliases in order to make your documentation more readable.
Consider this example code:
/** ST documentation
* foobar
* \exclusive for andi's function \endif
*/
void andreas(void);
/** ST documentation
* foobar
* \exclusive for beni's function \endif
*/
void benjamin(void);
You may use this alias in your Doxyfile: exclusive=\if SECTION_DEFINE \xrefitem viparea "Exclusive" "VIPs".
As long as SECTION_DEFINE is not defined, the "exclusive" information will not be included in your documentation. As soon as this section is defined, a "related page" (here: viparea.html) is created in your HTML documentation containing your documented items (here: andreas and benjamin) with the exclusive paragraph behind the command. The result:
I want to create and link to a central glossary using doxygen.
For creating the glossary, I would use a "glossary.md" file in my doxygen search path. The content is available through "related pages".
Would it be possible to link to entries in this glossary page from anywhere in my documentation?
Best regards
Andreas
I was able to solve the problem using the sections command and references onto them, but more elegant solutions would be welcome.
So my glossary.md file looks like:
#section GLOSSARY_ISR ISR
Interrupt service routine: ...
In my Doxyfile I added
ALIASES = "glos{1}=[\1](\ref GLOSSARY_\1)"
to be able to use a simple syntax from my code documentation as the following
Therefore an \glos{ISR} is used
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 have created a number of custom pages within Doxygen. I would like to customize the the order of the pages in the main menu. Below is a picture of my current navigation menu. I would like to change the order so Overview is first, Installation second, Introduction third, etc. Is there a way to do this?
After some investigation, it seems Doxygen currently does not support the ordering of pages in a custom (or any) fashion.
Just as #Toby mentions, the current way to ensure a desired order of pages in Doxygen is to ensure the page conditions (\page) are parsed in the same order. For instance, you can achieve the desired order by specifying your files manually such as:
INPUT = Developers.dox \
Hive_Training.dox \
Installation.dox \
Introduction.dox \
Models.dox \
Overview.dox \
Users.dox \
Files.dox
This is not ideal at all, but it works. What I found is that if you wish to maintain using directory paths in your Doxygen configuration file, you can create an 'page order' file to parse first before any other content. For instance:
INPUT += PageOrder.dox
INPUT += ../my_module_1/content/
INPUT += ../my_module_2/content/
And you add all the page references in a PageOrder.dox file:
\page developers Developers
\page hive_training Hive Training
\page installation Installation
\page introduction Introduction
\page models Models
\page overview Overview
\page users Users
\page files Files
This again, is not ideal; however, your maintenance process now resides in a single page order file (instead of touching one (1) or more Doxygen configuration files).
Doxygen processes the custom pages files names in alphabetical order.
Therefore you can name your custom pages files like :
_1_file1.dox
_2_file2.dox
etc...
As a result they will appear in the same order in the generated document. This solutions avoids modifying any configuration file!
A way for grouping HTML/ CHM output is via nested #page and #subpage elements in different files.
So what I've done in the past is to to have a landing page plus several 'strucutre' pages that define the section layout. Each reference needs to be in its own file.
As an exmple:
\mainpage
# Welcome to my main page #
Some text
\subpage IntroductionSection
\subpage DetailsSection
\subpage SamplesSection
And then have a structure for each subage like (IntroStructure.md)
Introduction {#IntroductionSection}
===============
# An introduciton to the topic #
\subpage GettingStarted
\subpage HowTo
\subpage DeepDive
Note that every subpage needs to be referenced with
Deep dive {#DeepDive}
again.
Thats the way I handle quite a bunch of markdown documents.
Works great for html/ chm although you have a certain file overhead.
I found one, rather cumbersome, method of achieving this.
Previously I had all my custom doxygen files (images, pages, etc) in one directory named input.
I have each of my pages in a separate file (e.g. main_page.dox, page1.dox, page2.dox, etc)
I moved my custom pages to a separate directory named pages at the same level as the input directory.
(I also renamed my input dir to images, and changed the IMAGE_PATH accordingly)
Then, in the doxygen config file I added the explicit paths to each page file to the INPUT variable in the order that I wanted them. E.G:
INPUT= . Documentation\images \
Documentation\pages\main_page.dox \
Documentation\pages\page2.dox \
Documentation\pages\page3.dox
This means that every time I add a new page I have to add its path to the INPUT, so as I said at the top, it's cumbersome. But better than having conlusions showing up before introductions etc
This works for HTML and LaTeX - haven't tested with other formats
I know this question is rather old, but its 2017 and I still haven't found a satisfying answer...
Since this is the first search hit, I thought I should still leave my workaround here.
I think the easiest and least cumbersome way is to go through the indirection of a single page, containing all your custom pages as subpages. This preserves the input order, e.g. ->
#page page_contents Contents
#tableofcontents
#subpage page_intro Intro
#subpage page_install Install
#subpage page_system System
I have added this to a class comment:
#link http://www.google.com Google #endlink
However, when I generate documentation using doxygen, the link text is indeed "Google", but the link is to:
file:///media/portable/Examples/Doxygen/link/html/classClass1.html
Can anyone explain what is going wrong?
I think you are using \link incorrectly. From the doxygen documentation, \link is used to refer to objects like a file, class or member and takes a reference to one of these as its first argument. For example, if I wanted to refer to a class method func in the class myClass, I would use
\link myClass::func link text ... \endlink
with all of the remaining arguments considered to be text for a link. I think your problem is that you do not pass a valid object as the first argument. I would guess that classClass1 is the next object in the file where you tried to include the link and this is what the \link command is refering to.
Linking to URLs
Doxygen will generate URL links automatically, so there is no need to surround the link with \link and \endlink or any other commands. So remove those and see if that fixes the problem.
To manually specify link text, use the HTML 'a' tag:
link text
For more information about how doxygen handles automatic linking see this documentation page.