I am using Doxygen to generate documentation for my project and I have a small issue. The report ignores folders specified, but still creates a huge header that links to code in the folders that I ignored.
I am using 3rd party code and I placed that into a folder named vendor. To ignore this code I placed the following in my doxygen config.
EXCLUDE_PATTERNS = */build/*
EXCLUDE_PATTERNS += */test/*
EXCLUDE_PATTERNS += */vendor/*
Now the reports are not created but still links in the header(picture). My code currently does not include or use the vendor code. My jenkins pipeline builds it.
The first step in my pipeline is doxygen to ensure the report is only generated on the untouched source code.
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
What is the proper way of delivering temporary build-time assets using nuget?
I am making a nuget package with a single file, which dependent projects require during the build phase. I would like the content of the file to be copied to obj\$(Configuration) folder inside a dependent project before proceeding with the rest of the build. Of course, the obj folder is temporary, so I would like my file to be copied there again as part of the next build if obj gets cleared out.
I tried contentFiles approach described here. This takes care of packaging my file inside nupkg file, but I was unable to set it up so that my file gets delivered (and re-delivered) to obj\$(Configuration).
You're looking for NuGet's MSBuild extensibility. Unfortunately it means you'll need to learn a bit about MSBuild if you don't already know it. I recommend running msbuild -bl or dotnet build -bl, which will create a msbuild.binlog file, which you can view with the msbuild structured log viewer.
One option is to have a target that creates the file in the intermediate output directory at an appropriate time (probably need to use BeforeTargets). You could use the Inputs and Outputs attributes to have msbuild do incremental build checks and skip copying when it doesn't need to, possibly making the build a little faster.
However, unless the file is has dynmanic content, copying the file is a waste. it's just going to be included as an item in another part of the build process. So, if it's static content, you could just create the relevant item in your targets file from your package's extracted directory, and then it's just as good as if it was copied to the intermediate output directory, without wasted time and duplicated disk space.
I am using Conan package manager on Windows to create a package. The conan command to create the package copies files to a folder within %USERPROFILE%\.conan (or C:\Users\xxxxxxx\.conan). Then from this location it builds a Visual Studio project and ultimately calls doxygen.exe to create a .chm help file in a post-build command. The doxygen command fails with:
error : failed to run html help compiler on index.hhp
Further investigation reveals the hhc.exe command executed by doxygen is failing with:
C:\Users\xxxxxxx\.conan\data\Module\1.0.0\user\channel\build\524dc97e4a3dd1f774ea3897f9e4faf26c5457d2\Documentation>"C:/Program Files (x86)/HTML Help Workshop/hhc.exe" html\index.hhp
HHC5010: Error: Cannot open "C:\Users\xxxxxxx\data\Module\1.0.0\user\channel\build\524dc97e4a3dd1f774ea3897f9e4faf26c5457d2\Documentation\html\Module.chm". Compilation stopped.
Close inspection reveals that in the error message, the ".conan" folder is missing. Sure enough, I confirmed that hhc.exe fails when the index.hpp resides in a folder that has a parent folder that starts with a ".".
Attempts to resolve this:
changing the Doxyfile setting OUTPUT_DIRECTORY to "$(TMP)/DoxygenModule" resolves the error, but creates the .chm file in another location, which I do not prefer.
navigating to the 8DOT3 name of the ".conan" folder, which is "CONAN~1", to run the hhc.exe command, succeeds, but unfortunately I have no way of getting conan to use this 8DOT3 path for creating the package. E.g. C:\Users\xxxxxxx\CONAN~1\...
I can live with the using the %TMP% folder but would prefer generating the .chm in the current folder. Anyone have any ideas?
HTML Help Workshop v1.31 is installed on my machine at C:\Program Files (x86)\HTML Help Workshop, probably from a Visual Studio installation (not sure). I attempted using a version downloaded from Microsoft website (v1.30) as well, which made no difference.
Other info: Conan version 1.18.0, Doxygen version 1.8.14, Windows 10 Version 1809
Unfortunately not a solution, but this is a known limitation in the hhc.exe, see: https://social.msdn.microsoft.com/Forums/en-US/0681145c-223b-498c-b7bf-be83209cbf4e/issue-with-html-workshop-in-a-windows-container?forum=visualstudiogeneral
HTML Help 1.x command line compiler hhc.exe cannot compile CHM file to folder whose full path contains folder name starting with dot. If you have that problem, you probably specified output path with folder starting with dot, e.g. "d:\My files.NET\documentation". You can use dots in folder names but not at the beginning.
Edit 2019-11-15:
I've just pushed a proposed patch to github (pull request 7402, https://github.com/doxygen/doxygen/pull/7402).
This proposed patch changes inside doxygen from the current directory to the short named current directory, but just for the HTML Help compilation.
Edit 2019-11-16:
Code has been integrated in the master version on github.
This is not an answer either. Actually, you found the answer and workaround[s] yourself.
Use OUTPUT_DIRECTORY to specify a directory containing no folder names beginning with periods.
The error you described is a known issue of the MS HTML Help compiler. More general, the HTML Help compiler does not like some folder and file names. Try and stick with these characters _, a..z, A..Z, 0..9. Do not use these signs in particular ., -, # .
Please note that the proprietary CHM file format is about 20 years old (Windows 95, ...). HTML Help is in maintenance mode, which means no new features and bug fixes are expected for either the runtime or the compiler. All mainstream development on HH has stopped.
There is no way to avoid this error if a directory name above begins with a period. Not even if only the necessary files are written by Doxygen and compiling of the index.hhp is done by a third-party tool like FAR HTML using your path that contains .conan. This is because all applications are using the faulty HHA.dll.
The above applies of course to the entire workflow you have described. Maybe you can interrupt it.
Doxygen can be configured not to call the HTMLHelp compiler. Just uncheck the GENERATE_HTMLHELP option (DoxyWizard: Experts > Topics > HTML). You have all files generated by Doxygen in your preferred output directory - but of course without the CHM file. This can be imported later e.g. by HelpNDoc and compiled as a CHM file in another location.
If you can interrupt the workflow and can also make changes to Doxygen's settings, then a preference setting of OUTPUT_DIRECTORY to e.g. C:/CacheMenu/CONAN~1/DOXYGE~1 also works as expected (here used as test case).
No matter what you do, your workaround and copy and paste from another directory outside is a quick solution at this stage. Please note the EDIT in #albert's answer.
I am creating a library and even though it is working perfectly fine by packaging all my code and putting all the header files in a folder and then zipping the folder and the static library, I just can't figure out the purpose of the "Copy Headers" section under Build Phases.
I have read all this links:
Using open source static libraries
Creating static libraries for iOS
How to create universal static libraries
Stackoverflow: copy headers: public vs private vs project
But I still do not see the point of setting the copy headers, I realize you can set the private and public path under build settings > packaging, and that the header files will go to that folder after build. But what is the point in this?, is this any different than not setting a single copy header file, and simply grabbing the .a file grab all my header files and put them in a folder?. Also what is the purpose of setting copy project headers?, since they are not included in the target at all?.
To my knowledge, adding the headers to the "Public" section of the "Copy Headers" phase is exactly the same as copying them in your release folder.
I use it as a convenience as I automate the library packaging process with a run script (thanks to this StackOverflow question which you should read if you want to provide universal libraries).
By doing this, I just need to add my new public headers to the "Public" section of the "Copy Headers" phase to have them automatically deployed in my release folder with this part of the script :
#########
#
# Added: StackOverflow suggestion to also copy "include" files
# (untested, but should work OK)
#
if [ -d "${CURRENTCONFIG_DEVICE_DIR}/usr/local/include" ]
then
mkdir -p "${CREATING_UNIVERSAL_DIR}/headers"
# * needs to be outside the double quotes?
cp "${CURRENTCONFIG_DEVICE_DIR}/usr/local/include/"* "${CREATING_UNIVERSAL_DIR}/headers"
fi
I've also noticed that those headers are copied in the package when archiving (Product -> Archive), so perhaps it's a first step from Apple to provide a clean way to build static libraries.
Hope this helps
Does the Copy Headers phase work now when producing an archive? Apple's documentation suggests that feature doesn't work and they suggested using a Copy Files build phase instead. Has this been fixed in recent releases of Xcode? https://developer.apple.com/library/ios/#technotes/iOSStaticLibraries/Articles/creating.html
How can you ignore files by Doxygen similarly as by Git's .git/info/exclude?
Doxygen generates docs for me based on 3rd party codes such Email -component and of my Git -repo, which I do not want.
I need to keep the files where they are.
You can use the EXCLUDE_PATTERNS tag in the configuration file:
EXCLUDE_PATTERNS = */test/*
Taken from here.