I'm updating some Doxygen documentation, and when Doxygen generates the code blocks for the documentation, it no longer puts the code in a block when it's surrounded by the \code and \endcode tags.
Original:
New:
The documentation was originally generated with 1.6.1, and the new documentation is using 1.8.1.2. Since the versions are different, do I now have to use the markdown syntax to generate the proper code blocks, or can I continue to use the \code tags?
No, \code..\endcode still works as always.
What is like the problem is that you use a custom page header or stylesheet (i.e. HTML_STYLESHEET or HTML_HEADER is not empty in the config file) and the newer version of doxygen started using different CSS tags to style the code block, and these are missing from your stylesheet.
Doxygen recently introduced a HTML_EXTRA_STYLESHEET option which you can use to overrule parts of the original stylesheet. I recommend to use that option instead of HTML_STYLESHEET.
Related
I have a rather complex project and I want to document it using doxygen.
I have no problem documenting the code and I also managed to have a nice front-page using a custom README.md file coupled with "USE_MDFILE_AS_MAINPAGE = README.md" directive in Doxyfile.
I defined several groups (#defgroup) which show up as "Modules" in my documentation.
I would like to add a "main page" to each of the group giving general information, beside the customary function/variable/type documentation.
I tried adding custom MODULENAME.md files coupled with matching #includedoc MODULENAME.md entries in group definition, it seem to work (I see several lines like: "Generating docs for page md_mcu_noitr_coro_README..."), but I cannot find if and where the page is linked (I expected to see it in the "Detailed Description" for the module, as it happens if I put some documentation inline where I put the "#includedoc" directive.
a snippet of one of my modules is:
/**
* #file coro.h
* #brief definition of coroutine implementing functions.
*
* #date: Feb 8, 2018
* #author: myself
*
* #defgroup coro "Coroutine implementation in plain 'C'."
*
* #includedoc mcu_noitr/coro/README.md
* #{
*
*/
What am I doing wrong?
Note: it is also a bit surprising I need to put the whole path from where my Doxyfile is, otherwise doxygen won't find it even if it's right beside the file containing the #includedoc command.
I also came across the problem that included files with Markdown formatted text via \includedoc or \include{doc} does not result in correctly interpreted Markdown. Note that I included Markdown files from other Markdown files. My work-around was to use the C pre-processor (cpp) - which is widely available - on Markdown files and use it's #include directive. You could of course use a true general text processor such as M4 as suggested in the cpp man page. Set FILTER_PATTERNS in Doxyfile as:
FILTER_PATTERNS = *.md="cpp -P -traditional-cpp"
You'll need the -P option to avoid it outputting line markers, which confuses Doxygen. -traditional-cpp was needed to avoid cpp eating white space that is important for the correct interpretation of Markdown. Don't use single quotes as this results in an error when Doxygen calls cpp via sh.
Then in my Markdown main page:
Main Page {#mainpage}
==========
Blah blah blah.
#include "other.md"
Using FILTER_PATTERNS instead of INPUT_FILTER avoids the problem about not being allowed to add or remove lines.
I have my markdown files in the same directory, I would guess that if they are located in different places you could tell cpp about it via -I, which would address your expectations about include paths on the issue you filed.
At the moment doxygen does not consider the fact that commands like \includedoc can contain markdown code. At the moment the only possibility would be to write a filter, see configuration parateter INPUT_FILTER in the doxygen configuration file, (not tested!) to replace the \includedoc` with the code of that file.
If I write some URL in source code comments like:
/**
* Here is an inline link [test](http://www.test.com).
* More information:
* test
*/
I enabled GENERATE_XML in Doxygen. This is what it generates:
<para>Here is an inline link [test](<ulink url="http://www.test.com">http://www.test.com</ulink>).
More information:
<ulink url="http://www.test.com">test</ulink> </para>
After converting the tags, I can create a Markdown content like:
Here is an inline link [test](http://www.test.com).
More information:
test
Note that the Markdown link [test](http://www.test.com) is polluted, which will break the link after I feed this into another Markdown processor. I need this as I want to write some markdown in comments, and extract it to some structured data formats for other tools to processing the markdown. I have disabled MARKDOWN_SUPPORT in Doxygen.
I have tried disable AUTOLINK_SUPPORT in doxyfile, but it can only disable internal type link to class/method/...
Solution for the mentioned problem, auto linking a web address, is to use [test](%http://www.test.com). By means of the % sign the (automatic) linking is suppressed.
In the documentation, paragraph "Step 3: Documenting the sources":
Links are created for words corresponding to documented classes (unless the word is preceded by a %; then the word will not be linked and the % sign is removed).
Note: in the above quote the wording is only for classes but it does work on other places as well. The same "problem" occurs in other places:
Description of AUTOLINK_SUPPORT
FAQ Doxygen automatically generates a link to the class MyClass somewhere
in the running text. How do I prevent that at a certain place?
Paragraph Links to classes
Paragraph "\%"
I am trying to separate out internal and external documentation using the doxygen constructs of cond; but i just cant seem to get get it working. I would essentially like to exclude some files completely and not conditionally. Regardless of where i add the tag (before include, before header guards etc) , the files and source both show up.
What i have tried in vain is to take the test file from doxegen repo for
conditional test and add it to the project.
Steps to reproduce [Linux]
create a new directory.
copy paste the above file (had to rename it to .h as .c was passed over?).
generate dummy config via doxygen -g.
update Doxyfile ENABLED_SECTION = COND_ENABLED.
Run doxygen.
check html/index.html
This however is still visible in the html documentation it generates for the project. I have set the ENABLED_SECTION variable with other values , but cond_enabled function still shows up. Running the testing directory of the project (doxygen) it passes. So i am lost.
Any suggestions?
Tried with latest version 1.8.14.
Thanks!
Regarding the \cond problems (not an answer directly to the real problem you face, I think, but to long for a comment).
The mentioned file is used in the, limited, testing doxygen can do / does and the first lines contain some instructions on what to do. Furthermore there is a default Doxyfile with the tests in use. It is hard to run a separate test outside the doxygen build tree.
Regarding the remark "Running the testing directory of the project (doxygen) it passes." This is correct, here, at the moment, only testing is done against the XML output and the generated output is compared to a once created version of the XML output. No tests are done, at the moment, in respect to HTML or PDF / LaTeX. Recently the test framework has been slightly extended so in the future this should be possible (compare the xhtml and tex output, but some work has still to be done here).
The version of the parser sees the \cond in the first line (normal C comment) as a doxygen command and skips everything till the first \endcond (your friend in these cases is always doxygen -d preprocessor). I think that removing / modifying the first line will result in an already better result. There is however another hiccup for e.g. HTML output. As the function cond_enabled is not documented and EXPAND_ALL is not set to YES the function will not appear in the documentation. So best is also to add a line of documentation with the function cond_enabled.
Regarding the seen HTML problems I modified the the relevant test in doxygen slightly and pushed a proposed patch to github (pull request 714, https://github.com/doxygen/doxygen/pull/714).
Note: the problem of skipping the \cond in normal C comment is quite a bit harder to implement (seen the logical complexity of the doxygen code in pre.l and commentcnv.l.
EDIT: 2018/06/10: The push request has been integrated in the master version on github.
I am trying to include a .ini file in the doxygen documentation of a C++ class, using \include. This works fine, but for some reason, doxygen treats the contents of the file as C code, which leads to strange formatting. I know \include surrounds the included file with a \code block, and that you can pass specific language information to the code block by using e.g. \code{.unparsed}. Is there a way to do the same with \include? \include{.unparsed} does not work...
Seems the answer to the question is "no": you cannot indicate a language when using \include, since doxygen tries to determine the language based on the extension. If it fails to do so, it reverts to C. If you do not want C formatting for unsupported file extensions, you can use \verbinclude instead of \include.
To distinguish this question from Doxygen: Adding a custom link under the "Related Pages" section which has an accepted answer that is not a real answer to the question, I specifically add prewritten to the question.
What I want:
Write one document tex file (without preamble, since this file will be \input-ed into a full document)
Import the document into Doxygen's HTML output.
Using Doxygen to produce tex file will probably not work, since it does too much layout work [This holds for its HTML output too like empty table rows 2015]. If Doxygen takes some other input that can easily be transformed into LaTeX, that will do.
You can easily add an already existing Latex file to your doxygen documentation using \latexonly\input{yourfile}\endlatexonly.
I would assume you put it e.g. under a doxygen \page.