Is it possible to wikify Visual Studio XML comments? - visual-studio

Is it possible to generate a set of wiki pages from XML comment file generated by Visual Studio?
I'm talking about something like Sandcastle, but for wiki format instead of compiled CHM.
Edit: I'm using MediaWiki which can import/export articles in XML. So I hope that it is possible to write a transformation converting XML comments to MediaWiki XML.

I'd recommend a bit different solution:
Use Help Server to publish .CHM/.HxS on the web
Use special MediaWiki templates to link reference from Wiki like here.
Use <see href="..."> to link Wiki pages from XML comments
See also: FiXml
This is not exactly what you wanted, but I hope this will be helpful.

If the items mentioned above do not suffice, have you tried to simply build your own XSLT transform into the wiki markup of your choice?
You can write a simple application in .NET (or pick your platform of choice) to transform the doc XML format to wiki XML format. You'd still have to keep the wiki updated with the output files manually.

Related

Does an open source markup->HTML tool exist for Confluence wiki markup?

There are many libraries for transforming markups like reStructuredText and markdown to HTML. I have some users who are familiar with the markup used in Atlassian's Confluence wiki product, which is unfortunately proprietary -- is there any open source compiler for the confluence wiki markup format, or possibly something that would transform it to an intermediate format?
I think Confluence uses the Textile markup format. I have used over the last few years a rails application that used the gem RedCloth to do the transformation, and I could switch between the 2 formats. I never checked if it is complete interchangeable, however.
You could check for yourself if it is sufficient at Try RedCloth.

Itextsharp documentation for xml

I am looking for documentation on the XML parser in ItextSharp, I heard there was a dtd years ago but this seems to be defunt. Does anyone know where I can find out all the valid tags and references?
I am using ItextSharp with Spark
Thanks
When in doubt, use the source. Poking around in my copy of the current iText source, I see that the only SimpleXMLDocHandler available is HTMLWorker.
And if you look at the source for HtmlTags.cs, you'll see all the tag and attribute constants HTMLWorker uses.
It's not exactly comprehensive, but is going to be getting some Enhancement in the immediate future.
I don't see a 4.1.2 tag, but there's one for 4.1.6 in the iTextSharp project on SF. It shows ITextHandler using a bunch of constants from ElementTag in HandleStartingTags(). It also uses ElementFactory to build the various supported tags. Looking at the source for each function will tell you which attributes it supports.

Code Documentation for ASP.NET + VB.NET application

We have a very old application dating back to ASP era which we are gradually refactoring to ASP.NET + VB.NET codebase.
It contains a lots of files with the below types:
aspx, asmx, ascx, vb, js (JavaScript), html, vbs (VBScript).
The backend database is SQL Server 2005 with lots of sprocs.
We would like to create a code documentation automatically generated from the comments in the code files. I liked Doxygen very much but seems like it does not support the above technologies. Can you please suggest some document generator tools, preferably a single tool or a group of tools?
Thanks a lot.
Ajit.
You can take a look at Microsoft's Sandcastle tool. I've used it many times, and it generates documentation based on the comments provided in your .NET code. If I remember correctly, it can also generate documentation for JavaScript libraries.
There are some out there:
SandCastle
NDOC
i've used SandCastle and it works too good if you have xml comments in your code.
You first enable xml documentation in your project by setting it in Project Properties -> Compile -> Generate XML Documentation.
Once done you may have to set treat warnings as errors, so that the studio can point out to you where and all the XML comments are missing.
To add an XML Comment, you place your cursor before a class definition or a function definition and type
///
This will automatically generate xml tags for documentation and then once you are done, you can import the project and start to build the documentation.
The good part is, if you have documented your classes well, when you use those functions in your application upon mouse over you can find the description which you wrote, much like how intellisense documentation works.
Let me know if you run into any other issues.
My last suggestion, make a hello world project and xml document it and get used to sandcastle with it.

Author in wiki, generate PDF documents, CHM files or embedded help

Anyone know of a wiki or wiki plugin that generates a PDF file or CHM file that spans the entire wiki?
I would like to have control of the table of contents.
I would like the internal and external links to work.
Ideally allow for tweaking the output template, but that is not a deal-breaker.
I want to generate content using WIKI syntax and mindset (lots of cross-links etc), but ship the content in PDF, CHM or an embedded application form. Something friendlier than installing the wiki software on the enduser machine...
XWiki does this out of the box.
The MediaWiki PDF Export extension allows you to select a group of PDF pages. I've not installed it yet, so unsure if it's easy to use that feature to select all the pages.
Confluence lets you choose pages when you export to PDF a space
But you can't customise a lot the PDF
You can customise it slightly through a theme (based on velocity)
Sphinx (https://www.sphinx-doc.org) is a fairly nice tool for generating HTML (or CHM) and PDF documentation, with wiki-like syntax. It is not a wiki; you can't edit through the web and generating HTML requires a build process. Still, it is pretty nice, with cross-references, fairly simple markup, and (in the HTML output) a search engine implemented in JavaScript with no server-side dependencies beyond static file hosting. Sphinx was developed for the new version of the Python documentation and is pretty themable; for example, the GeoServer project (which I work on, excuse the shameless plug) is using Sphinx with a custom theme for the new version of their user and developer manuals.
JIRA (http://www.atlassian.com/software/jira/default.jsp) is your geeky wet dream in terms of control; it exports to PDF (amongst other) and you can have complete control of pages, TOC and other aspects, although expect some complexity to set it up.
Microsoft has an HtmlHelp Authoring tool that can create chm files from html files.
If you need the help files both on the web and within deployed applications, generating the help from the same files used on the web could be a great solution. If the help site was created using asp.net (ie database driven) it might be worth using basic styles and creating a tool to generate html files by reading in the served out pages?
Have a look at: http://msdn.microsoft.com/en-us/library/ms524239(VS.85).aspx
I guess one could also additionally then create a PDF from the Html pages?

Code syntax formatter for posting code on webpages

Is there a utility that will generate html or css for blocks of code (.net c#) when you post it on a website?
I have seen several websites with very nicely formatted code and I dont believe they do this manually.
Google prettify -
http://code.google.com/p/google-code-prettify/
I prefer Syntax Highlighter implementations (I'm using Wordpress plugin implementation for my blog).
Advantages
It is based on JavaScript and does
not care about what you have on the
server.
Posts with this formatting display
properly on different RSS feeds and
can be copied to clipboard.
It is trivial to extend syntax
rules. I'm using that to highlight
custom operators in Boo-based DSL (see sample post)
Multiple languages are supported
out-of-the-box
(source: googlecode.com)
You can get JavaScript syntax-highlighting scripts, such as this one by Dean Edwards.
This is also a jQuery version apparently based on it which looks good.
CopySourceAsHtml is an add-in for Microsoft Visual Studio 2005 that allows you to copy source code, syntax highlighting, and line numbers as HTML.
http://copysourceashtml.codeplex.com
It's highly configurable, and works much better than the download page would make you expect! Don't know if there is something similar for VS 2008
If you don't have the ability to add the google prettifier CSS reference, this would be a better way to go, as what you get is a complete HTML with the required style. I use it all the time on our developers wiki, and loving it.
An even better solution, if you don't want to bother installing anything, is to just use the little web app I wrote called BlogTrog CodeWindow:
http://www.blogtrog.com
It's easy to use. Just paste your code and embed the results.

Resources