Doxygen lets you produce man page output, but as far as I can tell it only generates man pages for the actual code (functions, classes, etc). I have a great deal of information, such as examples, in a doxygen #mainpage comment that is not showing up anywhere in the man page output. I'd like to have it in that format so that I'll also have a man page that serves as an overall introduction. Is there a way of doing this with doxygen?
So far I have not found a way and the alternatives that I've explored don't work very well with the index.html file that doxygen creates for me. For example, I tried several different html2man scripts on the index.html file without success.
I came up with this work-around, which puts the pseudo-mainpage text in the man page, and puts a nice link to it from the HTML mainpage:
/**
* #mainpage
* Summary of my simple project. Please see #ref foo.h for more details.
*
* #file foo.h
* #brief Summary of my simple project.
*
* Here is the much more detailed description of my project,
* originally intended for the main page. Since I value the quality
* of man page output the most, this will end up on the individual
* file man page, and will be linked to from the HTML main page.
* I can rattle on with other things like...
* #todo find a better solution to the mainpage problem.
*/
As far as I can tell, this is not possible. HTML output covers the entire project, whereas man page output covers a single #file. The #mainpage applies to an entire project, not any particular #file. Therefore doxygen doesn't output the #mainpage for man output.
I downloaded the source, and browsed src/layout.cpp. Search (for example) for BriefDesc, and you will see how each "layout handler" is put together. I don't yet understand what #mainpage maps to, but clearly it's not something that's added in the "file layout handlers" section.
I tried adding #mainpage or #page, and using #ref to reference it, to see if I could create 2 man pages and manually tie them together and yet still have a nice HTML front page. For example, I tried to get 2 man pages, foo and foo-intro. To do this, I needed #page. But for HTML output, the intro shows up under "Related Pages", not "Main Page". And yet #mainpage can't seem to trigger a separate man page. Not ideal.
Have you included a #file <filename> comment in the file that holds the #main documentation and does <filename> definitely match the actual file name?
Doxygen will not include documentation from a file that does not have at least this.`
http://www.doxygen.nl/manual/commands.html#cmdfile
Related
When using markdown with doxygen, the documentation generates fine. However, I have one problem, which is that my documentation generates a related pages tab which is empty. For example, here is my main page:
# Project Name
Contents
This documentation is divided into the following sections:
- \subpage page_one
- \subpage page_two
And here is a sample subpage:
# Page One {#page_one}
Content
When I generate my documentation, I get the expected tree structure. However, when I click Related Pages, this is what I get:
Obviously, I have no benefit from an empty related pages tab. Thus, is there any way to get rid of this empty tab? If so, how should I change my Doxyfile?
You have defined the top page as USE_MDFILE_AS_MAINPAGE and all other pages are direct or indirect sub-pages of this page.
The display of the Related Pages is steered by means of the DoxygenLayout.xml (can be generated by means of doxygen -l, see also LAYOUT_FILE) and in here there is an item pages, when setting this item to no the Related Pages tab is not generated.
I have been using github pages with jekyll for auto-generating my blog using markdown documents.
I would like to use reference-style links then show a list of the links at the bottom of the page.
basically, I want the reference-style links to be printed on the page, by default they are hidden.
The idea is to have a list of references that a reader can refer to for more information.
for example, the following text:
# some header
...some body text in the blog with a link to [wikipedia][1]
...
...
# reference links
[1]: https://www.wikipedia.org
should generate the following output:
some header
...some body text in the blog with a link to wikipedia
...
...
reference links
[1]: https://www.wikipedia.org
As seen, the reference-style link is used in the markdown but it is also displayed on the page.
The previous "correct" output was achieved by duplicating each line and escaping the special characters, but this seems a bit redundant.
Can this be achieved by changes to _config.yml or using ruby? Other options are also welcome (css magic?).
tldr; I want a way to "unhide" the reference-style links at the bottom of my markdown page.
First, you have to understand exactly what is doing what:
Your markdown parser is converting your markdown into html.
Jekyll is taking that html and organizing it into pages.
GitHub pages is serving up those html pages.
The client reads that html and executes any JavaScript, etc.
The problem is that the markdown parser doesn't include the reference links at the bottom of the page. It's not like they're there but hidden. They simply aren't there. So you aren't going to find a CSS solution, because there isn't anything to style. You might be able to accomplish this with a custom markdown parser that includes the reference links in the generated html, but that won't work with GitHub pages and is probably going to be pretty hackish.
Another option is to execute JavaScript that uses document.links to get every link on the page, then output them in a <ul> or something at the bottom of the page. Something like this:
var links = document.links;
for(var i = 0; i < links.length; i++) {
var linkHref = document.createTextNode(links[i].href);
var lineBreak = document.createElement("br");
document.body.appendChild(linkHref);
document.body.appendChild(lineBreak);
}
You might restrict that to only include links in a certain div (like this), that way you don't have to parse out your navigation links and whatnot. You also have to consider the order.
Another option might be to include them in each post's frontmatter as a yml list, then show those in the layout that displays the post.
Of course, you could also simply create the reference yourself using markdown.
I'm trying to achieve the same functionality as Qt is having for their documentation with navigation path working same as Windows 7-8 (maybe also vista) i.e. showing whole path from root (module M) to component C and class X. M->C->X
Good example:
http://doc.qt.io/qt-4.8/qnetworksession.html
Must I put some kind of doxygen tags for root and it's child's their subchild's? I checked all the doxygen tags without seeing anything related to navigation path.
I am working with doxygen 1.8.7 which generates navigation path in footer, but everything i click is being displayed as root. Also, how can i put navigation on top of the page/header?
And is it possible to have group table of content displayed? I am having separated model.dox file for each module, which defines new group and contains sections/subsections. Any ideas why table of contents isn't displayed? Everything works well on (main) page using \mainpage \page tag.
Example of my group:
/*! \defgroup module1 CommonModule
*
* \tableofcontents
*
* Module description ..
* \section first Init
*/
Update 14.7.2014:
Didn't realize Qt documentation is build using qdoc tool, not doxygen so Edit section can be ignored. Questions still remain the same. From what I've experienced it is impossible to group pages and groups together therefor making it impossible to generate module page with list of all classes/namespaces/enums etc. Hopefully I am wrong.
Update 11.9.2014:
Page can not contain autogenerated list of all classes/namespaces/enums etc.
Doxygen navigation only shows file path when browsing over file list which isn't that useful since i am mostly browsing the documentation by class/namespace not by file and wish to have file list generation disabled.
Edit:
From checking Qt documentation (source) i see that Qt modules are all doxygen pages and modules page is manually written and not auto generated by doxygen since they probably couldn't get module description with table of content using \defgroup. Will do he same if needed.
Navigation path on the other hand is still a big mystery, they might have used some kind of internal scripting as i see custom tags such as \nextpage. It's strange how it's so difficult to find anything related to doxygen navigation on google!
I would like to know if there is any possibility to embed mediawiki pages in the javadoc view in eclipse?
We maintain a wiki with informations related to our modules, some functionality, specific problems that were encountered and other stuff. I would like to bring this documentation closer to our codebase. Moving everything from the wiki to javadoc is not possible, because the wiki is also accessible to people, who do not access code and there is also a lack of support for images in javadoc.
I thought of something like displaying the wikipage that is named like the class, whos javadoc I am currently viewing or using special javadoc tags.
Thanks for answers
you could add Links in your JavaDoc to your wiki with html-code. You can use the links without the #see tag, so it is not listed at the bottom of your doc.
/**
* #see http://google.com
*/
you can open the links in the JavaDoc-View in Eclipse, so it will not ne opened in the source-view.
I searched high and low and cannot a button tag in any of the javaScript that is generated that referred to step 7 of the tutorial. I must be looking in the wrong places, or I'm generating the code incorrectly. I generated the code in the three different levels of detail. Can anyone point me in the right direction who's completed the tutorial or is more experience with the GWT? Looked in every file inside of the war directory. Of course I could have missed one! :-/ Would definitely like to be able to find this stuff on my own when I begin development.
Here's the link:
http://code.google.com/webtoolkit/doc/latest/tutorial/style.html
Look under 3. Associating style rules with GWT-generated HTML elements. What I'm specifically trying to find is the tag.
<button class="gwt-Button" tabindex="0" type="button">Add</button>
Of course you don't have to do the tutorial any project you've worked on should have similiar tags to be found I just can't find the file containing them...
I did find some stuff containing gwt-Button class name on line 3078 of one of those "unique" file names, but the way the author stated it made me think this process would be "easier". This was generated using the pretty compile.
function $Button(this$static, html){
$ButtonBase(this$static, ($clinit_21() , $doc).createElement("<BUTTON type='button'><\/BUTTON>"));
this$static.element['className'] = 'gwt-Button';
this$static.element.innerHTML = html || '';
return this$static;
}
This looks like it could be used to generate the tag. Is this a combination of some javaScript and some javaScript library code like JQuery or Prototype?
Thanks
The best way I know to see the javascript generated by GWT is to use the Brain.jar DOM Viewer http://www.brainjar.com/dhtml/domviewer/
It's not the most user friendly, but if you click around, you can generally find the InnerHTML of some element that corresponds to the whole web page, and then search for "button" or the relevant keyword.