I'm using doxygen for my C++ project documentation. The project's version related API is version.hpp, generated from version.hpp.in via cmake's configure_file commands. Thus, version.hpp is located in #CMAKE_BINARY_DIR instead of CMAKE_SOURCE_DIR.
Here comes the question: I documented version.hpp.in, generated doxygen page from version.hpp, but I would like to mark the APIs' including path as ${CMAKE_SOURCE_DIR} (a relative path), instead of ${CMAKE_BINARY_DIR} ( a full path). How can I do that?
The resolution is, mark the redundant directory prefix in Doxyfile.in
STRIP_FROM_PATH = #CMAKE_BINARY_DIR#/include
Reference:
How do i remove the source path in doxygen
Related
Short version:
If I wanted to develop a completely new jsDoc template from scratch, what would I have to read to understand what jsDoc does, what interface my template must provide and what data I get to work with?
Long version:
I've been using jsDoc for a while now and have come across some tags that I would like to add and overview pages that I would like to have generated out of my documentation. Up to now I solved all my "user problems" with usejsdoc.org. I even managed to add a new jsdoc plugin that adds some tags. However, I can't find any developer documentation on how to create templates for jsdoc. I use ink-docstrap so I clicked my way through the template-folder (publish.js, /tmpl, etc.) and somehow got the idea of how everything works. But its very very time consuming.
What should I read to become a jsDoc template pro?
These instructions are the closest I could find:
To create or use your own template:
Create a folder with the same name as your template (for example, mycooltemplate).
Within the template folder, create a file named publish.js. This file must be a CommonJS module that exports a method named publish.
For example:
/** #module publish */
/**
* Generate documentation output.
*
* #param {TAFFY} data - A TaffyDB collection representing
* all the symbols documented in your code.
* #param {object} opts - An object with options information.
*/
exports.publish = function(data, opts) {
// do stuff here to generate your output files
};
To invoke JSDoc 3 with your own template, use the -t command line option, and specify the path to your template folder:
./jsdoc mycode.js -t /path/to/mycooltemplate
Failing that, you can read the source code!
I am running into a similar difficulty with lack of documentation. There is a GitHub issue that has been open for 7 years on this: Provide docs that explain how templates work.
The only example I've found so far of a custom template that doesn't look like just a modified version of the default is Ramda's documentation. It looks like they use a completely custom publish.js script that uses handlebars.js instead of underscore.js templates, constructs a non-hierarchical nav, pulls info from #sig and #category tags, and uses links to github for 'view source' instead of rendering its own html pages for source code.
Some of their code will be difficult to understand unless you are familiar with Ramda and functional programming (they use Ramda itself in their version of publish.js) but dumping out the values of data and docs during execution should help provide insight into what is going on.
It is helpful as well that their template is a single file so you don't have to jump between a lot of partial template files to follow how the doc is constructed.
I've just published my own new jsdoc theme. What I did is I simply copied the default template: https://github.com/jsdoc3/jsdoc/tree/master/templates/default, and worked on that.
I also managed to add grunt with the following features:
* transcompile + minify js files
* parse sass styles and minify them
* refresh the docs when you change something
You can see how it works here: https://github.com/SoftwareBrothers/better-docs
you can customize one of existing templates (default, haruki or silent):
go into node_modules/jsdoc/template and grab on of them into your app directory outside node_modules.
feel free to rename the dir ex: jsdoc-template.
open jsdoc-template update/customize the content as you want. ex: open publish.js find Home and replace My Js App.
update jsdoc.json by adding:
"opts": {
"template": "jsdoc-template"
}
another option to use one of those templates too: jsdoc3 template list examples
Followup to my previous comment about Ramda's JSDoc template. I've since created a customized version of it and published it on GitHub at https://github.com/eluv-io/elv-ramdoc
This is tailored for my company's projects, but it may be helpful as another learning tool. It adds a 'Show private' checkbox, updates Bootstrap to v5.13, replaces Handlebars with Pug, adds JSDoc comments to the publish.js script itself, and supports setting an environment variable to dump data to console during doc generation.
I have added a \dir comment to give a directory additional documentation. But I am unable to link to that directory documentation using any of the doxygen linking techniques that I know. My question is: how do I properly link to the documentation of a directory?
Below is a snippet of what I have tried. I get two warnings and no generated links. The Automatic Linking section of doxygen manual discusses Links to other members, but it does not mention links to dirs. Is linking to directory documentation supported? If so, am I doing something wrong or is this a bug? (I am using 1.8.10 right now. 1.8.9.1 behaved the same way.)
Here is what I have tried. I have documented the directory using
/// \dir cpp/vtutil
///
/// \brief Brief description of the dir cpp/vtutil goes here
///
/// \details A more detailed description goes here.
///
And I reference the directory using
/// \file
/// \brief Implements the vt application class.
///
/// This file is in the \ref cpp/vtutil directory.
/// What about #cpp/vtutil
Here are the warnings:
warning : unable to resolve reference to `cpp/vtutil' for \ref command
warning : explicit link request to 'cpp' could not be resolved
The documentation is used for the directory, but there does not seem to be a way to reference it. I sincerely appreciate any help.
The correct way to link to the documentation page for a directory is to use the \ref command. Explicit links using # are not supported for directories.
/// \file
/// \brief Implements the vt application class.
///
/// This file is in the \ref cpp/vtutil directory.
This example will generate a link to the documentation of the cpp/vtutil folder. One does, however, need to be careful when using absolute paths and the doxygen configuration setting with STRIP_FROM_PATH. When I run doxygen with the working directory in the source tree, I can get the correct link reference. But when I run from a build directory, which is different from my source directory, and need to use STRIP_FROM_PATH, then I have problems.
Doxygen is pretty forgiving or flexible with the path used when documenting a directory with the \dir command, but it is rather picky when referencing it with the \ref command.
This is how I fixed this issue, which I would consider a bug in Doxygen.
The accepted solution doesn't work for me. The only way I have found to link to a directory is using the absolute path name:
/// \brief Documentation linking to a directory
///
/// The files are in the \ref /home/user/project/include/subdir "include/subdir" directory.
By using \ref target "label", we avoid having the full path in the documentation, which of course is given by the development environment and unrelated to the end user's installation directory.
But we now still have the absolute path in the sources. A different developer will likely have a different path, so that the above solution is only usable by a single developer.
Instead, I added to my Doxyfile.in file the following alias:
ALIASES += "link_to_subdir=\ref #PROJECT_SOURCE_DIR#/include/subdir \"include/subdir\""
The documentation now looks like this:
/// \brief Documentation linking to a directory
///
/// The files are in the \link_to_subdir directory.
Doxyfile.in is a file that CMake parses to generate the Doxyfile that is used by Doxygen. I think it is a fairly standard way of using Doxygen (other build generators have the same functionality, and could be used instead). For example, my Doxyfile.in contains stuff like:
PROJECT_NAME = "#PROJECT_NAME#"
PROJECT_NUMBER = #PROJECT_VERSION#
OUTPUT_DIRECTORY = #CMAKE_INSTALL_PREFIX#/#DOCUMENTATION_OUTPUT#
INPUT = #PROJECT_SOURCE_DIR#/include
In CMake there is a command:
configure_file("${CMAKE_CURRENT_LIST_DIR}/documentation/Doxyfile.in" "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" #ONLY)
Thus, CMake will fill in the project's root directory where it says #PROJECT_SOURCE_DIR#, leading to an absolute path in the documentation as parsed by Doxygen, but with this path being dependent on the current development environment.
I'm just trying to begin develop a game in Marmalade (6.3). But when I have made my new sources (.cpp, and .h) and added them to the mkb, and then trying to run my program, then I got an error which says that Unable to find file.cpp in path(s). It's for all of my files except the files (game.h, game.cpp, main.cpp) which were made by Marmalade when I have chosen the new 2D game project. Should I add my .cpp and .h files to anywhere else?
Thanks
It is difficult to give a categorical answer without more info. However my guess is that you've copied and pasted from an example and not understood about the syntax of the files section. Basically:
files
{
(foo)
humbug.cpp
)
The "(foo)" might look very innocent, but it actually says that humbug.cpp is actually in directory foo - relative to the mkb file. It is common practice to actually use "(source)" and put all the source files in a directory of that name - making the source layout a bit neater.
Naturally if you have (source) and don't put the files actually in directory source, they won't be found. My guess is that is what you are seeing.
Just to clarify previous answer, The format of files directive is like this -
files
{
(<Path relative to MKB>,<Alternate Path>)
["Name of the parent Group in VS/XCode project","Name of the subparent group"]
fileName.cpp
fileName.h
}
for example I have two files SoundManager.h and SoundManager.cpp in System folder of Source, while MainMenu.h and MainMenu.cpp in Source/UI. Now the files directive would be -
files
{
(Source/System)
["Source","System"] #This part is not required, it's just to arrange your files in IDE project
SoundManager.h
SoundManager.cpp
(Source/UI)
("Source","UI")
MainMenu.h
ManinMenu.cpp
}
after building a web app, I tried out the jsdoc-toolkit. In a config file I added my index.html to the list of source files and also used the x-parameter to make the toolkit aware of the html file.
java -jar jsrun.jar app\run.js -t=templates\jsdoc -x=html,js -c=conf\my.conf
While the doc is generated without any errors, it still ignores any jsdoc annotation I made within the index file.
And when I check the generated doc, the index.html file is listed as source file.
Very simple documentations such as
/**
* testing the doc
* #constructor
*/
function Test(){
}
are simply ignored
Probably because its embedded in tags.
Do you have any idea how to force jsdoc to use this code as well?
Cheers,
zbug
I have a large amount of code that I'm running doxygen against. To improve performance I'm trying to break it into modules and merge the result into one set of docs. I thought tag files would do the trick, but either I have it configured wrong or I'm misunderstanding how it works.
The directories are laid out:
root +
|-src+
| |-a
|
|-doc+
|-a.dox
|-main.dox
|-main.md
|-output+
|-a+
| |-html
|-main+
|-html
In addition to 'a' there are other peer directories but am starting with one.
a.dox generates output and a tag file into root/doc/output
OUTPUT_DIRECTORY=output/a
GENERATE_TAGFILE = output/a/a.tag
INPUT=../src/a
main.dox just inputs the markdown file that has a mainpage tag and refers to the other projects tag file.
OUTPUT_DIRECTORY=output/main
INPUT = main.md
TAGFILES=output/a/a.tag=output/a/html
Should this merge or link all the docs under main where I can browse 'a' globals, modules, pages, etc? Or does this only generate links to 'a' if I explicitly cross-reference a documented entity in 'a' from inside of 'main'?
If this should work, any thoughts on where my syntax is incorrect? I've tried various ways to define TAGFILES, is the output directory relative to the main.dox file? To the a.tag file? Or to the a/html directory?
If I'm off base an TAGFILES don't work this way, is there another way to merge sets of doxygen directories into one?
Thanks.
I suggest you read this topic on how I recommend to use tag files and the conditions that should apply: https://stackoverflow.com/a/8247993/784672
To answer your first question: doxygen will in general not merge the various index files together (then no performance would be gained). Although for a part you can still get external members in the index by setting ALLEXTERNALS to YES.
Doxygen will (auto)link symbols from other sources imported via a tag file. So in general you should divide your code into more or less self-contained modules/components/libraries, and if one such module depends on another, then import its tag file so that doxygen can link to the other documentation set. If you run doxygen twice (once for the tag file and once for the documentation) you can also resolve cyclic dependencies if you have them.
In my case I made a custom index page with links to all modules, and made a custom entry in the menu of each generated page that linked back to this index (see http://www.doxygen.nl/manual/customize.html#layout) how to add a user defined entry to the navigation menu/tree.