I have a simple doxygen project consisting of Doxyfile and a configuration file, project.txt. In the project.txt file, I have some manually written documentation that uses cross-references to auto generated documentation from my code, and it all works fine.
I am trying to break down my project into subsections, like:
project.txt
disclaimer.txt
readme.txt
So, I've put Doxygen markup code into disclaimer.txt and readme.txt, and I updated the EXAMPLE_PATH in my Doxyfile to be:
EXAMPLE_PATH=./
Finally, in project.txt, I just added the lines:
\include disclaimer.txt
\include readme.txt
I expected disclaimer.txt and readme.txt to be imported into project.txt so they are treated as Doyxgen markup, but instead, they are interpreted as text, and are rendered as-is in a code block, as if wrapped by \code and \endcode tags, making the include operation useless.
Is there some way to include additional Doxygen configuration files and actually have them parsed?
Thank you.
Quoting the docs:
\include This command can be used to include a source file as a block of code.
Which seems to agree with the behaviour you see.
I am not sure if you can include pages into others as you want.
The best solution I can see is to use \subpage instead, which will both create a link to the other pages and make them subpages of the main page (this will show in the html related pages section as a dropdown hierarchy).
Usage inside project.txt would be:
\subpage disclaimer
\subpage readme
Supposing that disclaimer.txt contains a line like \page disclaimer Disclaimer
Also make sure that *.txt is in your FILE_PATTERNS.
I don't think you can include Doxygen config files at arbitrary points in your code like that. I know you could add it to you file list though, etc:
INPUT = ../PATH_TO_SOURCE_CODE_HEADER_1.h \
./project.txt \
./disclaimer.txt \
./readme.txt
Also, make sure each of your .txt files is wrapped with /** and */ if you're using C, for example.
Related
I am using Doxygen to create a product manual, and I ran into this issue.
Some links in the outputted PDF (created from LaTeX) are broken; they point to the first page of the document.
The accompanying HTML output does not suffer from this issue; links work just fine, as shown below:
The Doxygen code for this page:
/**
#mainpage [product] Developer's Guide
Blah blah blah.
This manual is divided into the following sections:
- #subpage intro
- #subpage [etc]
*/
Further notes:
I tried #ref instead of #subpage. No difference.
Some other references in the PDF are broken as well (automatic file references in some sections), but many work fine.
Here's the LaTeX intermediate for this page:
This manual is divided into the following section\-:
\begin{DoxyItemize}
\item \hyperlink{intro}{Product Introduction}
[etc]
Edit: Manual Solution Found
Open refman.tex from the LaTeX output directory
Change the entry \hypertarget{d1/dfb/intro}{} to \hypertarget{intro}{}
Repeat for other pages
Run the LaTeX to PDF tool
This is obviously not a viable solution for automated processes though, so this question is definitely still open.
As stated in the answer provided by #aaronncfca. The problem is caused by the not proper handling of paths in case CREATE_SUBDIRS is set to YES.
A, proposed,patch has been created for this problem and pushed (pull request 328) to github
Valid workaround found: Disable CREATE_SUBDIRS in the Doxygen configuration (Expert tab, Project topic in doxywizard).
The issue (as shown in the manual solution in my question) is that Doxygen puts the path in the hypertarget thing, where only the symbol is needed. By eliminating the path entirely, disabling sub-directories fixes the issue.
I'm using Doxygen for generating documentation in my programming projects. And while I find it quite easy to configure and use I can't seem to find a way to hide the source references it adds to the HTML output.
I'm using these two directives in the configuration file:
SOURCE_BROWSER = NO
VERBATIM_HEADERS = NO
But it only seems to hide the "Definition at line of file ."
What I want removed is what's in the red rectangle below:
Is there a directive to also hide the source code it references? (Other than doing the hack'ish thing and remove it with CSS or jQuery)
Make sure your setting on INLINE_SOURCES is set to NO.
Description from the manual - it looks like you have this YES
Setting the INLINE_SOURCES tag to YES will include the body of functions, classes and enums directly into the documentation.
I am using Doxygen groups and therefore see them listed in the Doxygen navigation tree under Modules, as expected. My project is documenting integration using Zend modules and therefore Doxygen Modules and the Zend modules tend to overload the term modules and make it confusing for the readers. My question is: is there a way, preferably an automated way, to change the Doxygen term Modules in the tree and in the right pane pages to something else?
I've sucessfully changed the word 'Modules' in the past, but I've only ever needed to do this for the top-of-page tabs, and not the navigation tree. The method I used than may also work for you:
You need a fresh Layout file.
Generate one with doxygen -l layoutfilename.xml
Locate the line containing type="modules"
Change the title entry from "" to "Your Word" - I used "Index"
Specify the replacement layout file in you doxyfile.
After you did like the suggestion above.
If you want to manually replace it for PDF file that generates from latex you can open refman.tex go to %--- Begin generated contents --- and change to something like this:
(Note that I marked the lines you should edit with <========)
%--- Begin generated contents ---
\chapter{Main Page}
\label{index}\hypertarget{index}{}\input{index}
\chapter{Index Index} <========
\input{index} <========
\chapter{Index Documentation} <========
\input{whatever was here before}
%--- End generated contents ---
After that go to modules.tex and change the filename to index.tex (for this example).
Conceptually along the lines of restructuredtext, I want to distribute readme files throughout my different source directories and then have Doxygen read and include those readme text files as part of the generated Doxygen output.
How is this done? Or do I need to spoof Doxygen by creating a pseudo C file like:
README.h:
/**
My big long readme file describing how this library
was created and how it should be used
*/
namespace foo_readme { }
If you're just using HTML output you can just use the HTML_EXTRA_FILES field of the doxygen configuration file.
If you have a plain text README file just add it to your program directory manually.
You can also spoof a .h file with the tag \mainpage to populate the index (main) page of your doxygen output.
In doxygen.config
Add FILE_PATTERNS = README
Add INPUT = foo_dir
Then add comments to the foo_dir/README
/*!
* opus
* #brief amaze me
* #details do something amazing
*/
namespace README { }
If you create your README as a .md file, like a Bitbucket Readme, it will be included automatically by Doxygen in the Related Pages. You can also set USE_MDFILE_AS_MAINPAGE to a .md file for your front page.
I would like to start documenting my code properly, but am unsure where the best place is to put it for HeaderDoc to read. I read the following phrase in the HeaderDoc documentation which makes me think the intended location (from Apple's point of view) is in the header files?
Instead of specifying a single input file (as above), you can specify an input directory if you wish. HeaderDoc will process every .h file in the input directory (and all of its subdirectories), generating an output directory of HTML files for each header that contains HeaderDoc comments.
Is this right? Does it make a different where I put my documentation?