Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jaime-olivares/xmldoc2md
Automatic documentation markdown formatter for Visual Studio projects
https://github.com/jaime-olivares/xmldoc2md
build-automation markdown msbuild powershell-script stylesheets visual-studio xml-document
Last synced: 3 days ago
JSON representation
Automatic documentation markdown formatter for Visual Studio projects
- Host: GitHub
- URL: https://github.com/jaime-olivares/xmldoc2md
- Owner: jaime-olivares
- License: mit
- Created: 2015-09-16T14:04:59.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2016-09-15T05:32:24.000Z (about 8 years ago)
- Last Synced: 2024-09-19T04:53:31.536Z (8 days ago)
- Topics: build-automation, markdown, msbuild, powershell-script, stylesheets, visual-studio, xml-document
- Language: XSLT
- Size: 613 KB
- Stars: 29
- Watchers: 5
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# xmldoc2md
Automatic documentation markdown (.md) formatter for Visual Studio projects, specially for projects published in TFS and github.
## Background
Visual Studio provides a facility for generating documentation in XML format right from the normalized /// comments, as described here: https://msdn.microsoft.com/en-us/library/z04awywx.aspx
There are many tools out there for transforming the generated xml documentation, including Sandcastle and some XML stylesheet files that can be found here at CodeProject. The traditional output is HTML, because that's the most universal format. CHM (help) and RTF (rich-text) formats are also used.
An emerging popular rich-text file format is Markdown (see http://en.wikipedia.org/wiki/Markdown), as a simpler alternative to HTML and RTF. It is used in github for simple and formattable README files, and now it is supported by Team Foundation Server including its cloud version: visualstudio.com
## Generating automatic xml documentation
For enabling the generation of xml documentation, there is an option in the Project Properties window, as shown:
This option is per project and per build configuration. It is important to be aware of the output folder, which is relative to the solution's root.
## Points of Interest
As mentioned before, the documentation is generated from normalized xml comments inside the source code. Here is a fragment from the provided source code:
````
///
/// The unique class of the application
///
class Program
{
///
/// The entry point of the application
///
/// This is the unique functional method. All others are dummies
/// The argument list. Not used
static void Main(string[] args)
{
/* Code removed */
}
///
/// A dummy method
///
/// An integer argument
/// A string representation of the argument
/// Whenever a file error occurs
///
///
/// int x = 1;
/// string s = DummyMethod(x);
///
///
public string DummyMethod(int arg1)
{
this.DummyProperty = arg1.ToString();
return this.DummyProperty;
}
````
After compiling, the resulting documentation file is an xml with a specific schema (see https://msdn.microsoft.com/en-us/library/fsbx0t7x.aspx). For the source code above, it will have the following aspect:
````
XmlDoc2MD
The unique class of the application
The entry point of the application
This is the unique functional method. All others are dummies
The argument list. Not used
A dummy method
An integer argument
A string representation of the argument
Whenever a file error occurs
int x = 1;
string s = DummyMethod(x);
````
## Generation of the MD file
The Markdown file is generated with the help of two files: a XML stylesheet (.xsl) and a Powershell script (.ps1). The stylesheet contains all the transformations required for transforming the xml file into a non-xml markdown format. At this point it is important to point out that the provided stylesheet is still a work in progress, and will be great to receive feedback from stylesheet experts.
For educational purposes, the sample C# application itself takes the same XSL file for producing the MD file. The Powershell script is an equivalent of that source code.
The proposed way to use the tools is:
For each project
- Include the stylesheet into your project's root (xmldoc2md.xsl)
- Include the Powershell script into your project's root (xmldoc2md.ps1)
- Create a post-build event that invokes the Powershell script and uses the stylesheet, as shown:
Take into account that, for this example, the input XML is coincidentally called xmldoc2md.xml, but in fact it can have any arbitrary name, usually the project name with .xml extension.
Also it is very important to specify the correct paths to the input and output files, by using the Macros option.
If everything succeds, the resulting output is a markdown file with the formatted documentation. The final aspect will depend on the specific implementation. Visual Studio Online shows the following:
