I am trying to generate documentation from Matlab files like this
%> #file fooBar.m
%> #ingroup KEK
%> #brief Documentation file example.
Now title is this
fooBar.m File Reference
But I need this
fooBar Reference
Related
I've got a mainpage using a HTML table that I only want to be included in the HTML output of doxygen. It should not be included in the other outputs (currently only LaTeX).
Since that mainpage uses doxygen commands like \ref and \mainpage itself, the \htmlonly tag is unfortunately not an option.
Is there a way to limit a markup file to certain outputs only?
As suggested, I ended up running doxygen twice, once for HTML output and once for LaTeX output. This gives me the flexibility to change other settings for different outputs as well, which is also something I was looking at.
So the dox file for my mainpage now looks like
/**
\if MySpecialFlagForHTMLOnly
\mainpage notitle
...
\endif
**/
My default doxyfile has GENERATE_HTML = YES and GENERATE_LATEX = NO. It also defines MySpecialFlagForHTMLOnly in ENABLED_SECTIONS.
Now for a second automated run, I change both GENERATE_HTML and GENERATE_LATEX and clear MySpecialFlagForHTMLOnly from ENABLED_SECTIONS.
What I'd like to do:
I'd like to use rmarkdown to create rails *.html.erb files.
If you're unfamiliar with *.html.erb files, they're basically html files with ruby enclosed between <% and %> or between <%= and %> (latter if result should be included in final html rendering).
Problem:
I can not find a way to get rmarkdown to ignore <%, %>, <%= and everything between them.
Q: Any ideas how this might be done?
Thanks in advance.
I'm using Doxygen to document a project. In one file, I have a bunch of public functions that I want to put in a group. I do this as follows:
/**
#file myFile.c
#brief This is a file. It has stuff.
*/
/**
#defgroup my_group Group with myFile.c stuff
#{
*/
//CODE & STUFF WITH DOCUMENTATION
/**
#}
*/
The issue is that the LaTeX output contains all of the documentation here twice; once in the "Module Documentation" section and again in the "File Documentation" section. This amounts to maybe 25 pages of purely duplicate stuff in my end PDF file (generated from LaTeX).
An ideal fix would be to have the File Documentation for myFile.c say "See #ref my_group" or something like that. Is there a way to accomplish this in Doxygen?
Acceptable solution found:
Create a Doxygen layout XML file and configure Doxygen to use it (instructions)
Open the XML file; find the <group> tag; comment out the <detaileddescription> and <memberdef> sections
This resulted in only the list of members being produced in the "Module Documentation," with hyperlinks to the full member documentation within the "File Documentation" section in the LaTeX/PDF output. The HTML output already functioned this way, so it was not significantly changed.
When writing perlpod documentation that will be exported to HTML, can I embed the title of the resulting HTML file in the POD directives?
I want to be able to convert multiple POD text files to HTML with the pod2html command, and don't want to have to give the --title="My Title" parameter on the command-line.
For example, here is a text file with perlpod formatting:
=pod
=head1 This is a heading
This is some text. I'd like to set the title of this document in the resulting HTML file.
=cut
When I convert it to HTML, pod2html gives a warning about there being no title:
$ pod2html test.txt > test.html
/usr/bin/pod2html: no title for test.txt
In the resulting HTML file, the title is set to the filename (test.txt):
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>test.txt</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root#localhost" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li>This is a heading.</li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<hr />
<h1><a name="this_is_a_heading_">This is a heading.</a></h1>
<p>This is some text. I'd like to set the title of this document.</p>
</body>
</html>
I'd like to find a way to have the title given in the perpod document, perhaps with a directive like this:
=title This is my custom title
In the Perl documentation, I see that the document titles are set nicely. Is this all done without having the document title in the pod document itself?
There is nothing in the Pod documentation that controls the title of the document. This up to the program that converts the Pod documentation to the format you want. Most of the pod2doc programs that you use to generate the documentation will have a module like Pod::Text or Pod::Html. These do most of the grunt work in converting.
pod2html takes a --title parameter. However, what you want is for pod2html to do it without you having to specify it. What you can do is roll your own version of pod2html. Let's look at pod2html script itself, and maybe you can figure out what you can do to get what you want.
Removing all the POD document, I see::
use Pod::Html
pod2html #ARGV
That's the entire program.
It looks like you could make a pod2steve program to do what you want. You want to take the last parameter (which I assume is what you want the title to be), and simply pass it through the pod2html subroutine. Your pod2steve would look something like this:
use strict;
use warnings;
use Pod::Html
my $program_name = $ARGV[$#ARGV];
pod2html --title=$program_name #ARGV
That should work.
No.
POD exists mainly¹ to write Perl module documentation², and therefore doesn't have many fancy features. Also, the primary output medium for POD is the terminal, where no such thing as a title exists conceptially³. It is, after all, just Plain and Old documentation.
1. Suprisingly many Perl books are written in POD.
2. The location of the POD document coincides with the thing discussed in the text.
3. The ps name / $0 variable comes close, but is useless here.
This is also a technical problem: pod2html uses Pod::Html, which parses the command line, and wraps itself around Pod::Simple::XHTML or something, without doing, or interfering with, the actual parsing. However, it already supplies a header and a footer, which sensibly overrides any default headers that might be emitted.
There are two interesting options how your problem can be solved:
You write a postprocessor that puts the value of the first h1 into the title. This should be <10 lines in a parser with XPath-support. Then you write a little script that ties these together, and can be invoked instead of pod2html.
You take the existing wealth of POD parsers (and source code), and whip up your own HTML from POD generator. If all you are actually doing is a small fork, you could try to offer the modification to the original module.
Doxygen noob here. I've searched and tried to resolve this for several hours now with no luck. The answer is likely to be something obvious I'm not familiar enough to see.
EDIT: Doxygen's #par command breaks the HTML output page (running doxy 1.8.0 via gui wizard), by either failing to insert an <b> inside the <dt>, or by inserting an errant </b> inside the </dt>, while similar commands (like #return and #note, for example) do not. Example comment (comment is on a function, if this matters...):
/**
Register a new exit to the room object. Adds the exit to our exit_hash map with some safety checks for whether we've been passed an array of exits or just one.
New practice; there's now an exit hash map ([direction:hash])
and we add exits into our hash map as they're created. This is how guards
are now identified: they're assigned the hashes they guard as IDs.
#code
PLEASE WORK
#endcode
#return hrm
\note
This note consists of two paragraphs.
This is the first paragraph.
\par User defined paragraph:
Contents of the paragraph.
\par
New paragraph under the same heading.
\par
And this is the second paragraph.
More normal text.
*/
You may recognize part of the comment, as I've lifted it from the doxygen demonstration of the command's usage. This produces HTML output that ceases at "This is the first paragraph." under the \note command (all sections before this render properly), and the top of the doxygen page cites the error:
This page contains the following errors:
error on line 422 at column 42: Opening and ending tag mismatch: dt line 0 and b
Below is a rendering of the page up to the first error.
The XML renders (or appears to me, at least) properly and is as follows:
<detaileddescription>
<para>Adds the exit to our exit_hash map with some safety checks for whether we've been passed an array of exits or just one.</para>
<para>New practice; there's now an exit hash map ([direction:hash]) and we add exits into our hash map as they're created. This is how guards are now identified: they're assigned the hashes they guard as IDs.</para>
<para><programlisting><codeline><highlight class="normal">OH<sp/>JESUS<sp/>GOD<sp/>PLEASE<sp/>WORK</highlight></codeline></programlisting></para>
<para>
<simplesect kind="return"><para>hrm</para></simplesect>
<simplesect kind="note"><para>This note consists of two paragraphs. This is the first paragraph.</para></simplesect>
<simplesect kind="par"><title>User defined paragraph:</title><para>Contents of the paragraph.</para></simplesect>
<simplesect kind="par"><title></title><para>New paragraph under the same heading.</para></simplesect>
<simplesect kind="par"><title></title><para>And this is the second paragraph.</para></simplesect>
More normal text.
</para>
</detaileddescription>
HTML output at the error site:
<p>Register a new exit to the room object. </p>
<p>Adds the exit to our exit_hash map with some safety checks for whether we've been passed an array of exits or just one.</p>
<p>New practice; there's now an exit hash map ([direction:hash]) and we add exits into our hash map as they're created. This is how guards are now identified: they're assigned the hashes they guard as IDs.</p>
<div class="fragment"><pre class="fragment">OH JESUS GOD PLEASE WORK
</pre></div><dl class="section return"><dt>Returns:</dt><dd>hrm</dd></dl>
<dl class="section note"><dt>Note:</dt><dd>This note consists of two paragraphs. This is the first paragraph.</dd></dl>
<dl class="section user"><dt></b></dt><dd>And this is the second paragraph.</dd></dl>
<dl class="section user"><dt>User defined paragraph:</b></dt><dd>Contents of the paragraph.</dd></dl>
<dl class="section user"><dt></b></dt><dd>New paragraph under the same heading.</dd></dl>
<dl class="section user"><dt></b></dt><dd>And this is the second paragraph.</dd></dl>
<p>More normal text. </p>
I am in the same situation. Have .xhtml as my extension due to .svg dot diagrams. I have found that if you put an extra new line before and after #code blocks it seems to solve a lot of the problems:
/**
* #par Example:
* This is an example:
* #code
* // Some code
* #endcode
* The above example is AWESOME!
*/
The above creates XHTML errors but if I change it to:
/**
* #par Example:
* This is an example:
*
* #code
* // Some code
* #endcode
*
* The above example is AWESOME!
*/
Everything is fine again. This may or may not be a solution to your problem but has allowed me to keep my .xhtml extension whilst working around the doxygen XHTML output.
I'm not sure but part of your problem may be that you are using a paragraph title on one of the paragraphs in your \note. From the doxygen manual page for \par:
If no paragraph title is given this command will start a new paragraph. This will also work inside other paragraph commands (like \param or \warning) without ending that command.
Which implies that adding a title will end any previous command block. Try re-ordering your documentation to match the \par documentation example and see if that produces the results you expect.
Also, what is on line 422?
I've been toggling options/searching for errors in the comment format for days and it looks like I've finally isolated the issue, which I'll document here should someone else come looking:
I had set the HTML_FILE_EXTENSION option to .xhtml as recommended in the documentation for the DOT_IMAGE_FORMAT setting:
The DOT_IMAGE_FORMAT tag can be used to set the image format of the images generated by dot. Possible values are svg, png, jpg, or gif. If left blank png will be used.
Note:
If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files visible in IE 9+ (other browsers do not have this requirement).
This setting isn't the cause of the error (bug report: https://bugzilla.gnome.org/show_bug.cgi?id=672472), but the setting was causing it to prevent the page from loading due to the unpaired tags. Returning this setting to .html doesn't resolve the issue of the extra </b> tag, but it does function as a workaround to keep it from breaking the page for now.