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.
Related
GitHub supports asciidoc readme files, but it looks like "include" is not supported.
I want to use doctoolchain which can render and export to html and pdf (and maybe into other formats). This tool works great.
I could use raw.githack.com to show the generated html file from the GitHub repository.
But I think it would be a good idea to have the result also as one (1) readme.adoc file.
How to export into one (1) asciidoc file, which I could use as it is as readme file so that github will render it and show? Best would be to use doctoolchain, when this tool will render my documentation it could also generate the one-file-asciidoc-documentation.
I think internally asciidoctor collects and merge all these "include" files. So maybe this file is already available in any place? The doctoolchain build folder contains only the target files.
You are right there is a long dicussion why includeis not supported by github.
You can achieve your goal with doctoolChain and pandoc(https://pandoc.org/). Following steps are required:
configure your docDir/Config.groovy
inputFiles should have docbook defined
inputFiles = [[file: 'yourfile', formats['docbook']]]
run the doctoolchain task generateDocbook - it creates ???.xml file somewhere in docDir/build
generate from the generated docbook again an asciidoctor file - `pandoc <FILENAME_OF_GENERATED_DOCBOOK.XML> -f docbook -t asciidoctor -o <FILENAME_OF_ASCIIDOCTOR_WHICH_HAS_EVERYTHING>
make sure it runs automatically and you commit it regulary
now you are ready
This script can be used to resolve includes and to generate one (1) output file:
https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb
some information about the script and possible next steps you can read here:
AsciiDoc Backend (AsciiDoc 2 AsciiDoc) for preprocessing
to use it, ruby and asciidoc must be installed:
asciidoctor.org/#installation
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
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
For instance I set the source code path as c:\code\testapp\src. Is this then available as a var I can use - for instance so I can spit out a tag file in a location relative to this, not relative to the working dir of doxygen? I think I'm looking for something like how Ant defines vars for just about everything and these can be re-used; does Doxygen have special vars for any of the config values?
I'm thinking like $PROJECT-NAME or %VERSION% or whatever...
You can use environment variables in the configuration file; the syntax is the same as in a makefile, i.e. $(VAR_NAME)
I am not sure, but I have seen people use variables as part of their build process. For example the lemon graph library uses cmake, sets a variable for the absolute file path in cmake and the doxygen config file includes variables such as #abs_top_srcdir#. Through the build process these variables are replaced with the relevant text.