When I upgraded from Doxygen 1.7.6.1 with custom options to 1.8.8 with the default Doxyfile options, the Nodes.xml file was not generated. Which option is needed to generate Nodes.xml?
GENERATE_DOCSET = YES
This option creates the following files:
Nodes.xml, Tokens.xml, makefile, and plist.info
Running makefile will copy your API's documentation to a pre-determined location where Xcode, upon starting, can find and load for use.
Related
I have written the documentation for a medium sized C++ piece of software using Doxygen together with Markdown. I am quite happy with it, as after changing the xml layer I ended up with something like that:
http://docs.mitk.org/nightly/index.html
I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation would be automatically built after a "git commit", and hosted to be browsed.
ReadtheDocs looks like the ideal site but uses Sphinx and reStructuredText as defaults. Doxygen can be used too, but AFAIK only through Breathe. Going through that route essentially means that I would need to re-structure all the documentation if I don't want to dump all the API documentation into a single page (http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).
Paradoxically, Doxygen is installed in the read-the-docs server, but after struggling I could not find a workaround to skip its Sphinx or Mkdocs.
I've tried the following solution to use Doxygen on Read The Docs and it seems to work:
set up empty sphinx project (refer to official sphinx doc),
in sphinx conf.py add command to build doxygen documentation,
use conf.py html_extra_path config directive to overwrite generated doxygen documentation over generated sphinx documentation.
I've tested this with following source tree:
.../doc/Doxyfile
/build/html
/sphinx/conf.py
/sphinx/index.rst
/sphinx/...
Some explanation:
in my setup doxygen generates its documentation in "doc/build/html",
ReadTheDocs runs its commands in directory where it finds conf.py file.
What to do:
add following lines in conf.py to generate doxygen docs:
import subprocess
subprocess.call('cd .. ; doxygen', shell=True)
update conf.py html_extra_path directive to:
html_extra_path = ['../build/html']
In this configuration ReadTheDocs should properly generate and store Doxygen html documentation.
todo:
other documentation formats, for example: pdf.
This answer builds upon the great one already given by "kzeslaf". So follow the steps described by him first, before you continue here.
While his answer works as intended, I had the problem that ReadTheDocs (RTD) uses a rather old version of Doxygen (1.8.13 at the time of writing). This caused several issues for me like the one reported here. Additionally, if you set up Doxygen to treat warnings as errors, you might need to override this option on RTD due to version-related warnings.
I found a simple solution to upgrade the Doxygen version on RTD using conda.
Create an environment.yml file somewhere in your project (probably in the documentation directory). The content is as follows:
name: RTD
channels:
- conda-forge
- defaults
dependencies:
- python=3.8
- doxygen=<VERSION>
Replace <VERSION> with any version number that you like to use and that is available on conda-forge. Use conda search doxygen -c conda-forge to get a list of all available versions or simply check this site. You can also remove =<VERSION> and conda should install the latest one automatically.
Now you need to create an RTD config file if you haven't done this already. Add the following lines:
conda:
environment: <DIRECTORY>/environment.yml
Replace <DIRECTORY> with the actual location of the environment.yml file (relative to your project root, for example: docs/environment.yml). Now, if you followed all the steps in the answer of "kzelaf" and the ones I mentioned, RTD should successfully build your Doxygen documentation with the version you selected. You can check it in the lower right corner of the created pages. Alternatively, add subprocess.run(["doxygen", "-v"]) to your conf.py and check the RTD build logs.
I'd like to know whether there is a way to change the default tool to generate message sequence charts (msc) of Doxygen. Actual default tool for Doxygen is the mscgen (http://www.mcternan.me.uk/mscgen/) and it's a good tool, but I'd like to use msc-gen (https://sites.google.com/site/mscgen2393/) that seems to be a more complete tool.
I've already tried to create a link at "MSCGEN_PATH = /usr/bin/" to the msc-gen (like ln -s /usr/bin/msc-gen ./mscgen) but command line of tools are different. There is a specific way to configure Doxygen to "learn" this new tool command line?
For the current msc-gen version (v4.0.0), your solution should work.
I just tried setting the MSCGEN_PATH to the msc-gen installation directory and it worked for me. msc-gen already brings a copy of its main executable with the name mscgen.exe to be called by doxygen.
This solution is also described in the second paragraph of:
http://msc-generator.sourceforge.net/help/4.0/
You may also like to have a look at Plant UML and its doxygen integration:
http://plantuml.com/index.html
http://plantuml.com/doxygen.html
Recently I started writing some doxygen docs in an existing project which already has quite a lot of doxygen comments.
Since I'm learning a bit - I like to iterate with making edits and generating docs, since doc generation is quite slow - 3-5min. This becomes un-workable.
I managed by deleting most of the files in the source tree so doxy only found the ones I was editing but this is really a horrible solution and not something I'd want to do frequently.
Is there a way (command line arg or env variable for eg) - to limit which files/modules are used for generating docs - so rebuilding docs can be done much faster?
Yes, you can customize Doxygen's behavior from either the command-line or via environment variables. For example, if you only want to include one file (include/somefile.h), you could execute Doxygen like:
( cat Doxyfile ; echo "INPUT=include/somefile.h" ) | doxygen -
see the Doxygen FAQ's "Can I configure doxygen from the command line?" for more details on customizing behavior from the command line.
Alternatively, if you want to use environment variables, you could use specify something like the following in your configuration file:
INPUT = $(FILE)
Doxygen performs environment variable substitution on its configuration files, allowing you to specify which file(s) should be acted on using:
export FILE=include/somefile.h
doxygen Doxyfile
See Doxygen Configuration for details on using environment variables in configuration files.
Has anyone had success using xcode 4 as an IDE for AVR microcontrollers? Is it possible to have the same amount of integration as the plugin for eclipse?
Yes. I use Xcode 4 as IDE when writing AVR code.
But it only works as a "wrapper" for the avc-gcc command line tools. I have three Xcode targets in the project: build ("make all": compile only), fuse ("make fuse": program fuses) and flash ("make flash": compile and download to AVR). Just select the appropriate target and hit Cmd-B to build.
There is not much integration. I still have to edit the Makefile to set clock frequency, programmer and device model and fuse values. And if I add more .c files I also have to add the corresponding .o file to the Makefile. But at least I can do it from within Xcode.
I have created a minimal project template that will allow you to create a new AVR project in Xcode. Get the file here http://dl.dropbox.com/u/1194636/AVR_Xcode4_template.zip. Extract the archive and put the Atmel AVR® folder into ~/Library/Developer/Xcode/Templates (you might need to create the Templates folder).
Template from second answer (http://dl.dropbox.com/u/1194636/AVR_Xcode4_template.zip) works fine but with some tweaks.. You have to put these in file "makefile" in the template to be able to include multiple files in the project:
OBJECTS = main.o $(OBJ)
SRC = mynewfile.c
OBJDIR = .
OBJ = $(SRC:%.c=$(OBJDIR)/%.o)
LST = $(SRC:%.c=$(OBJDIR)/%.lst)
in SRC section you need to enter all files that are built in the project (for example mynewfile.c).
One more enhancement is to clear all the obj files from the project, after the linking ... Find the section main.hex in makefile and change rm -f line with following
rm -f main.hex $(OBJ) $(LST) main.o
Other then that, everything stays the same. What i couldnt find out is how i can enable code complete for this template. If anyone knows i would appreciate the help.
Due to the fact that we need to integrate the Zend Framework on our project root, and that generating that documentation will be useless and take long time, I would like to generate documentation for all files inside application folder only.
Does anyone know how I can generate documentation for a specific project folder, trough Netbeans 7.0 interface?
Update:
The best I've found so far was to:
Open the terminal window from netbeans, and type:
sudo phpdoc -d public_html/yoursite.dev/application/ -t public_html/yoursite.dev/docs/
Update 2
Let's suppose our Zend library is inside projectrootname/library/Zend we also can try, by going to: Tools > Options > Php > PhpDoc and place the following:
/usr/bin/phpdoc -i library/Zend/ -o HTML:frames:earthli
At least for me, that doesn't seem to work, because, when I try to generate the documentation, I get permission error issues displayed on the output window.
Thanks
The -d/--directory option [1] should be used to highlight the most high-level code directory that you want phpDocumentor to start reading from. If your Zend folder is at or above the level of your application directory, then just using --directory /path/to/application should help you document only your application code.
If your Zend folder is somewhere inside your application (e.g. in your app's ./lib folder), then you can use the -i/--ignore option [2] to tell phpDocumentor about any directories that it will see but should ignore, --ignore *zend*. Just be aware that formatting your ignore value can be tricky, so see the examples in the manual. Also, be aware that as phpDocumentor runs, you will see these ignored folders and files being listed in the output... phpDocumentor "ignores" them by not generating docs for those files. It does, however, still need to parse them, in case those objects are referenced in files that do get documented.
[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.directory
[2] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.ignore