Class Documentation Suggestions

Question

We are a Microsoft store focused on using C #. We have several projects, including websites, Windows services, and class libraries that include XML comments.

I am looking to create HTML documentation in MSDN format for each project and deploy it in a centralized location that all developers can easily get. I also want to automate these steps so that they can be run at regular intervals so that I and other developers do not need to remember how to create and deploy new documentation whenever changes occur. I looked at Sandcastle and Doxygen, and both of them look like good options for creating the documentation I want, but I need advice so that it can automate its creation, for example, in night work or something like that.

Anyone out there doing something like that? I am not for sale, but the end result is HTML; especially if there is a better idea.

EDIT:

I appreciate all the good ideas. Now there are several routes that I can explore, but I will not know what will work best until I evaporate my hands. Sandcastle's hint file maker seems to be offering me the best options for what I want to do, so I will give a nod to this suggestion. However, if I had more time to work with the XSLT and CSS solution to get the XML data in order, I would prefer this suggestion first.

Thanks again everyone!

Answer 1

Take a look at Sandcastle Tooltip Designer . This uses stand-alone projects, so you can create them as often as you like (for example, at night or as part of your continuous integration system every time a change is noted).

Answer 2

You do not need third-party tools to create good documentation: the C # compiler can output documentation from XML comments to XML, and all you need to do is create good CSS to display it in a browser. If you are not satisfied, you can also create your own XSLT transformation before applying CSS, as described here (see CSS example in the comments!).

Alternatively, you can take this XML documentation and improve it using something like NDoc . Here is a good article on how to do this, unfortunately, somewhat outdated.

You can manually create only the documentation for your project in a single XML file by running the compiler with the /doc:documentationfilename.xml parameter.

You can also specify in Visual Studio (Project Properties → Documentation) to add this option to each assembly of your project so that an XML file is generated every time you create a project. You can then hook up post-build events to copy the XML file to your repository.

You can also configure MS Build on Team Foundation Server to create your documentation and copy it to the repository in the same way ( /p:DocumentationFile=fileName.xml );

Answer 3

I do this with our projects. We mainly use doxywizard to configure the Doxyfile configuration, which will set the specifications for the generated html. Then, in the build server step, I call "doxygen doxyfile".

Our Doxyfile is configured to create doxygen files in the area visible from our web server. Thus, each commit to the trunk causes the documentation to automatically rebuild.