I have a Qt-based C++ project and a Doxyfile to generate a documentation website for it. I like the include dependency graphs enabled by INCLUDE_GRAPH and INCLUDED_BY_GRAPH. Sometimes, however, they get very cluttered by all the Qt headers included. (How) can I only display my own files there?
I tried adding EXCLUDE = /usr/include/qt, to no avail. This question has no answer, either.
Bit outdated but I have found the answer. Set up the INPUT_FILTER (under Expert/Input in doxywizard) to
sed -e "s:#include <Q.*>:// REMOVED:g"
This will preprocess any file that Doxygen analyses and replace all #include <QAnything> with comment // REMOVED.
Related
In my typescript & svelte project, I use prettier to format codes.
Also, I use prettier-plugin-organize-imports to automatically organize imports.
However, this plugin does not support svelte yet (it kind of works, but it's buggy), so I want to disable the plugin for *.svelte files while enabling it for *.ts files.
According to the official doc of prettier, it seems impossible to do this by adding options to config file (prettier.config.js).
Is there a good way?
You can create a .prettierignore to exclude files from formatting.
# Ignore artifacts:
build
coverage
# Ignore all HTML files:
*.html
Check the docs.
There have been a couple of threads on this topic in the past that claim Sphinx doesn't support this at all. I had my doubts but either it has been updated since or the documentation for it was quite well hidden, because here is a link on the website stating otherwise:
http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cpp-domain
Anyway, I'm new to Sphinx but am trying to use it to (eventually) automate documentation using some text from some source C++ code. So far I haven't been able to get anywhere when using the sphinx-apidoc -o ... command. An almost blank document is created. I'm probably not using the right directives, since I don't know how - the supporting documentation hasn't been able to help me.
Can anyone provide some assistance with the basic steps needed to get it working? If it is not possible to auto-generate documentation from C++, what are the C++ domains for and how to use them?
On auto-generating C++ documentation:
After reading up on how to use sphinx at all, you should have a look into breathe:
Breathe provides a bridge between the Sphinx and Doxygen documentation
systems.
It is an easy way to include Doxygen information in a set of
documentation generated by Sphinx. The aim is to produce an autodoc
like support for people who enjoy using Sphinx but work with languages
other than Python. The system relies on the Doxygen’s xml output.
So additionally, you'll need to follow Doxygen commenting style and even setup an doxygen project. But I tried that and it works really well after the initial setup took place. Here is an excerpt of our CMakeLists.txt which might give you an idea on how sphinx and doxygen work together:
macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
add_custom_target(${TARGET_NAME}
COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
WORKING_DIRECTORY docs
DEPENDS doxygen
COMMENT ${COMMENT_STR}
)
endmacro(add_sphinx_target)
add_custom_target(doxygen
COMMAND doxygen docs/doxygen.conf
COMMENT "Build doxygen xml files used by sphinx/breathe."
)
add_sphinx_target(docs-html
html
"Build html documentation"
)
So after initial setup, essentially it boils down to:
build doxygen documentation with doxygen path/to/config
cd into the directory where the sphinx configuration is.
build sphinx documentation with sphinx-build . path/to/output
On the c++ domain:
Sphinx is a „little bit“ more than a system to auto-generate documentation. I would suggest you have a look at the examples (and consider that the sphinx website itself is written in sphinx reST code). Especially click the Show Source link on many sphinx-generated pages.
So if you cannot generate documentation automatically for a project, you have to do it yourself. Basically sphinx is a reST to whatever (LaTeX, HTML, …) compiler. So you can write arbitrary text, but the advantage is that it has a lot of commands for documenting source code of different languages. Each language gets its own domain (prefix or namespace) to separate the namespaces of the different languages. So for example I can document a python function using:
.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
Does something nasty with timers in repetition
(source)
I can do the same using the cpp domain:
.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
Describes a method with parameters and types.
(source)
So if you want to document your c++ project without doxygen+breathe but with sphinx, you'll have to write the restructured text files yourself. This also means that you split the documentation from your source code, which can be undesirable.
I hope that clears things up a bit. For further reading I strongly suggest that you have a good read on the sphinx tutorial and documentation until you understood what it actually does.
I have some C++ code base, documented with doxygen, and build with GNU make.
Version information is centralized in makefile, where I have something like:
VERSION=1.2.3.4
In my makefile, the CFLAGS add the following define:
CFLAGS += -DAPP_VERSION=$(VERSION)
This enables me to get the version in code, like this:
#define STR_EXPAND(tok) #tok
#define STR(tok) STR_EXPAND(tok)
int main()
{
cout << "software version is << STR(APP_VERSION) << endl;
}
Now, what I would like is to have this in the doxygen-produced html files:
Current version of software is 1.2.3.4
I managed to export the makefile variable into the doxygen configuration file with:
(edit: doxygen is called from makefile, through a 'make-doc' target)
PREDEFINED = APP_VERSION=$(VERSION)
But then, if I try in the doxygen \mainpage command something like this, it fails, because (of course), macro names don't get expanded in comments...
/**
\mainpage this is the doc
Current version is $(APP_VERSION) -- or -- ... is APP_VERSION
*/
Questions
Do you know of a way to "expand" that macro in the doxygen comments ? This could be done by some sed processing on the file holding the comment in the makefile, but maybe this can be solved directly with doxygen ?
How do other projects handle versioning (besides automatic versioning tool that VCS provide, I mean), in a way that the version id is uniquely defined in a file, so it can be fetched both by software build system and documentation build system.
Related: How to display a defined value
Macros in comments are not generally expanded (see, for example, this answer). This is not unique to doxygen and I can 't think of a way to do this using the PREDEFINED configuration option.
As you state in the question, you can use sed, see the third bullet point in this answer. For example, using the following
INPUT_FILTER = "sed -e 's/VERSION/1.0/'"
will replace all instances of VERSION with 1.0 in all your source files (you can specify which files to process with INPUT_FILTER, rather than processing all source files). You might not want VERSION to be expanded everywhere, so perhaps it is best to use something like $(VERSION) and sed this token. Also, you will need a way of getting your version number from your makefile and into your doxygen configuration file. This can be done with another sed.
To address your last bullet point, doxygen has the FILE_VERSION_FILTER configuration option for determining the version number of each file. Using this will print some version information (whatever is printed to standard out from the command specified in FILE_VERSION_FILTER) at the top of each file page. In the documentation there are examples of getting the version number using a number of different version control systems. Also, here is a page describing how to use git and doxygen to extract version information.
The only drawback with this configuration option is that I don't know how to specify where the file version information should appear in the final documentation. I presume you can use a layout file: I presume you can change the layout of pages, but I have never done this and don't know how easy it would be to use this to include version information on the mainpage.
You need to use the "export" functionality of make ie a very simple make file with
project_name=FooBar
export project_name
all:
doxygen Doxyfile
Will allow you to use the following comments in C++
/*! \mainpage Project $(project_name) Lorem ipsum dolor
I can see this becoming a PITA with a large set of exports but it's a fairly simple way to do it. Alternatively you could run doxygen from a separate BASH script with all the exports in it to avoid polluting your Makefile too much.
the commands manual suggests that $(VARIABLE) expands environment variables. So maybe you can put your version in an environment variable?
I have a number of multiline macros defined in a file called macros.h. In my doxyfile, I've got
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = NO
yet Doxygen still will not expand the macros in any source file that includes macros.h. I ran "doxygen -d Preprocessor doxyfile" to see the output of the preprocessor, and it outputs messages like:
#include macros.h: not found or already included! skipping...
You've told your compiler about your include path, but you haven't told doxygen. So it tries to open "macros.h" and gets a file-not-found error.
You need to properly set INCLUDE_PATH in your Doxyfile.
#Ben: Have you actually gotten INCLUDE_PATH to work?
I understand the theory. I have set up the INCLUDE_PATH as explained (in both absolute and relative forms) but to no avail. I have set INCLUDE_FILE_PATTERNS to *.h. Nonetheless, when processing my .cpp files Doxygen finds all of the headers in the INPUT directory yet fails to find any headers in my lib/ subdirectory.
The only solutions I have found are:
1) Create a symbolic link within the INPUT directory to each header in its lib/ subdirectory. This is ugly and ungeneralizable.
2) Set the RECURSIVE tag to YES. This is undesirable because now the entire contents INPUT's tests/ subdirectory get added to the generated documentation.
I am inclined to believe that INCLUDE_PATH functionality is simply broken (at least in version 1.7.1 that I am running).
In a C++ iOS project (or any other Mac OS), is there a simple way of making a value available both to the Info.pList settings, and to the code in the form of a preprocessor macro?
Ideally, I would like to have something like this
C++ code:
#define MY_VERSION_STRING "1.0"
Info.pList
CFBundleVersion: ${MY_VERSION_STRING}
Or alternatively, is there a way of getting values from the .pList in c++? (Without manually parsing the .pList as xml.)
Probably not the best solution, but you could use the /usr/libexec/PlistBuddy utility in a build script to generate a .h file containing a define with a value extracted from the plist.
To output a value from a plist:
/usr/libexec/PlistBuddy -c 'Print :Path:To:Key' filename.plist
I know this has already been answered, but I'll add my two cents for posterity. As Richard mentioned above, Xcode has a couple of options for preprocessing Info.plist files -- the most relevant to the current question are "Preprocess Info.plist" and "Info.plist Preprocessor Prefix File".
If your version information is defined in, say ver.h, you can include ver.h as the prefix file and refer to the version macro directly from Info.plist.
This is all readily doable without involving PlistBuddy at all, entirely using build settings.
you create a user defined build setting for your project/target either in the Xcode UI or if you're familiar with xcconfig files you can define it there in a completely textual = form.
you create your setting MY_VERSION_STRING with a value of 1.0 as your build setting either in Xcode or in an xcconfig file.
in your Info.plist your CFBundleVersion line would have a value of ${MY_VERSION_STRING}
you turn on Info.plist preprocessing
lastly, make use of GCC_PREPROCESSOR_DEFINITIONS build variable. for that build setting you can specify a value of MY_VERSION_STRING=${MY_VERSION_STRING} which will result in your defined and shared build setting definition available in to your c/c++/obj-c code as if you had created it as a #define
Property list can also store arrays or some binary data. How do you represent that? It is very domain-specific. So if you know exactly how do you want each type to be represented in C++, you have to either parse plist file and generate C++ code, be that preprocessor directives, or some code defining arrays, enums etc. There are PlistBuddy and plutil tools available, but they probably won't be much of a help. The easiest way for me would be to use perl, see Using Perl to Manage Plist Files for details.
Good luck!
In case anyone wants to do the same thing, this is the script I added to the target before the compilation phase:
VERSION=`/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' Info.plist`
echo "#define VERSION_STRING L\"$VERSION\"" > Version.h
If you use #define..., you shoud use in the .plist key, MY_VERSION_STRING, and not ${MY_VERSION_STRING}. This works too with the "Info.plist Preprocessor Prefix File". In both cases don't forget to set "Preprocess Info.plist File".