There are doxygen commands #include, #htmlinclude, #verbinclude and the rest of the family. Each of them is equivalent to inlcuding the file inline and surrounding it with a pair of start and end tags like #code, #htmlonly, #verbatim etc.
For the life of me, I cannot find the doxygen command equivalent to just pasting a markdown file into the docblock without surrounding it with any tags that modify the interpretation of the included fragment.
Is this possible? How?
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.
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.
I'm trying to use \cite in Doxygen to produce a bibliography page and also a reference within my text. I have bibtex in my search path and a proper .bib file. I have added the .bib file to CITE_BIB_FILES and am using a proper BibTex label found in the .bib file. Doxygen is creating a bibliography page, but it is empty. It is also creating a citation link in the documentation text, but the link is also empty. Any idea how I can get the citation info displayed?
I was facing the same problem. There is an perl dependency to generate citation. So you must have both perl and bibtex in the system path.
Ignore the example above, that only applies to Latex, for doxygen use (Note: no braces):
\cite Hale
The .bib file has to be located in doxygen working directory.
Bibliographic References HTML page will be then produced by doxygen with:
[1]J. K. Hale. Theory of functional–differential equations. Springer–Verlag, Berlin–Heidelberg–New York, 1977.
for the following bib entry:
#BOOK{Hale,
author = "J. K. Hale",
title = "Theory of functional--differential equations",
publisher = "Springer--Verlag, Berlin--Heidelberg--New York",
year = 1977
}
In order for \cite to work properly you need:
be sure to put your file.bib in the working directory where you call doxygen Doxyfile
bibtex executable must be in the search path
perl executable must be in the search path
the RefName used in \cite RefName must have a corresponding entry in file.bib
Maybe a little late, but I had the same problem. Doxygen generated a bibliography for LaTeX output, but not for HTML output and none of the proposed answers worked for me.
As suggested by #Raffi, this seems to be a bug in Doxygen < 1.8.3. I used Doxygen 1.8.1.1 and it did not work. Then I installed Doxygen 1.8.3.1 without changing anything else and it worked fine.
When you set CITE_BIB_FILES in DoxyFile did you include the .bib extension on the filename?
Doxygen claims it will automatically add the .bib extension, but if you omit it doxygen seems to gets confused and doesn't generate the citelist.doc file properly.
Include .bib in the filename and it should work fine, at least that is the case for me.
In order to create a bibliography you need to instal Perl, and add it to the search path, along with bibtex. In the documentation
for CITE_BIB_FILES it says:
"The CITE_BIB_FILES ... To use this feature you need bibtex and perl available in the search path ... "
Is there a simple way to add something like the {Back to Worg's index} to every .org page in a directory which I plan to publish with org-publish-project-alist? Is this accomplished with a #+ tag, or some definition in the .css file?
I looked at how they did it on Worg, and it doesn't look like CSS.
There are a few ways you might be able to do so.
Create a generic file that only includes the details you want in each file. For example:
[[./index.org][Back to index]]
Then use #+include: <filename> at the location in your file where you want the line. (See Include Files)
Alternately you could define a macro in a setupfile (See In-Buffer Settings) that is the definition of the link (or multiple link choices)
#+macro: toIndex [[./index.org][Back to index]]
In both cases it is worth noting that the relative paths are based on the exported file. So a [[../index.org]] will always point to the index.org file in the parent directory, no matter where the setupfile is.
I'm writing a README.mediawiki file for my project called plainBlog on GitHub, but I want to add some inline code on it. What is the syntax for this? Also, what is the syntax for XML code (multiple lines)?
An example of inline code is located at github/markup, where we have lines like this: gem install wikicloth
There's a few:
Start each line with a space.
Text is '''preformatted''' and
''markups'' '''''can''''' be done
or:
<pre> Text is '''preformatted''' and
''markups'' '''''cannot''''' be done</pre>
For inline <code> spans there is no special syntax:
<code>Source code</code>
From http://www.mediawiki.org/wiki/Help:Formatting