4

Background

I write a lot of code in C#, and use XML comments all over the place to describe how my methods, members, and properties behave.

I would ultimately like to compile all of the information gathered from these comments (along with the methods, members, and property names) and generate a nice/readable document describing my API.

I know that there is some software already that does similar sorts of things, like SandCastle help-builder. I would like to stay away from using SandCastle though, and the Windows help files in general.

I would actually like to generate my document as a PDF if that is possible.

Question

Is there a free/open-source software out there for turning all of my XML comments into a nice PDF document?

  • 1
    "I would like to stay away from using SandCastle though, and the Windows help files in general." - could you elaborate a bit on the background of this, to help us make suggestions? I'm asking because SandCastle basically runs a partially XSLT-based transformation of the original Xml files to produce any kind of output format, not necessarily Windows help files. For instance, it can generate (more or less, depending on the style used) plain HTML files. – O. R. Mapper Oct 14 '16 at 10:08
  • Did you have a look at doxygen? it supports C# and also pdf output (through generatin LaTeX output that can be converted to a pdf). – albert Nov 13 '16 at 9:45
  • @albert Actually I did, but was only able to find source code for it. I have yet to see any implementation built with Doxygen that I could just run on my code and get the PDF output. If you know of such a thing then let me know. – Snoop Nov 14 '16 at 13:03
  • It is fairly easy to build doxygen from source, see www.doxygen.org for download instructions. Afterwards you have to build the pdf from Latex requiring some packages depending on your operating system. – albert Dec 4 '16 at 8:36
  • @albert I'd like to give that a try. Can you formalize what you're saying by throwing down an answer including some basic steps for getting started? – Snoop Dec 5 '16 at 12:28
0

We've got our own tooling that does this, and it's fairly complex, but it shows that it can be done. We do Java more than C#, and of course we're an XSLT shop, so that all probably colours our approach. We take the apidoc.xml output of the C# compiler as one input, another XML file produced by a crude parsing of the C# source code as a second input, then merge these together (using XSLT) into an XML file in a format that is compatible with the documentation of our Java APIs produced using javadoc and jeldoclet, combine this with the Java APIs, and then turn the result into a particular flavour of HTML5 that's compatible with the rest of our documentation, again using XSLT. We don't produce PDF these days, but we have done so in the past, using XSL-FO.

This of course is in-house tooling and it's not productised enough for anyone else to use, but I thought I would just describe it so you've (a) got evidence that it can be done, and (b) a measure of the complexity.

We were generally surprised how poor the tooling for this is in the .NET world compared with the Java equivalent. Perhaps things have changed since we built all this, I haven't looked recently.

  • Although it won't do PDFs, I am currently looking at Doxygen. Supposedly it will generate HTML, and then I could always do the conversion myself to a PDF if necessary. Thanks for your input though. – Snoop Jun 16 '16 at 10:36
  • doxygen can also create latex output and from this a pdf (Makefile and / or make.bat provided as well) – albert Jan 12 '17 at 18:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.