Login/Register
Can I generate .MD files from XML Documentation?
Asked Answered
Solved c#.netdocumentationxml-documentation
C

5

11

I have used Sandcastle to document my class libraries recently. However, I have recently discovered that Sandcastle is no longer developed by Microsoft: https://archive.codeplex.com/?p=sandcastle.

I have had a look online on GitHub and I see that lots of open source projects use .MD (MarkDown) files these days. I see that .MD files are supported by GitHub and TFS. How can I generate .MD files from XML Documentation files?

I have spent the last few hours Googling this. For example, I have found this with only a few hundred downloads: https://github.com/lijunle/Vsxmd/tree/master/Vsxmd I am not asking for tool recommendations. I am asking if it is possible to convert .XML Documentation to .MD files.

Castalia answered 23/4, 2018 at 20:10 Comment(0)
O
-8

Of course it is possible to generate markdown from XML comments. The obvious question is: Why? The best answer is: to generate a website from the markdown content.

DocFX is essentially the replacement to Sandcastle. I'm using it to generate a documentation website from XML comments in C# code.

Outlander answered 24/4, 2018 at 6:23 Comment(12)
Do you add the Nuget package (Docfx) to the project being documented? I don't like the idea of this as my domain model should be isolated. – Castalia
No, you would create a separate project, e.g. a class library, to house the documentation, or you could just call the docfx console tool separately from a build script, which is what I do. It's all on the website. – Outlander
Thanks. Does that mean that everytime you compile your project e.g. Domain Model, then it builds the documentation? – Castalia
Yes, you could get it to do that. Whether you'd want to is another question. You don't want to slow down your development waiting for documentation to build, so ideally you'd want to add another solution configuration which builds the documentation, and have that project not build in the Debug configuration. – Outlander
Finally, should the XML documentation be contained in .html files (in the _site folder) or in .md files? Please note that I am specifically referring to the XML documentation. – Castalia
DocFX will turn the XML comments into .html files. – Outlander
Do I have to tick XML Documentation in the build options (in Visual Studio). Ticking it or unticking it does not seem to make a difference for DocFX. However, it does make a difference for Sandcastle. Is that right? – Castalia
Could you answer the question above? Then I will mark the answer. +1 for the hyperlink in the answer. – Castalia
It doesn't make any difference for DocFX, as the DocFX console tool parses the XML comments directly from the source code. Sandcastle on the other hand relies on the XML Documentation file to be created. – Outlander
If I am using DocFX only then I can leave it unticked? Right? I am new to this tool and what to avoid gotchas. – Castalia
Yes, you can leave it unticked. – Outlander
The reason for converting it to Markdown is so that you can check it into Azure DevOps' wiki. – Torbert
A
10

Yes, it is possible.

There are a number of projects to do so out there. The one you found Vsxmd for example but also simpler ones like lontivero/593fc51f1208555112e0.

The process is basically reading and converting each XML element (or some of them) to their equivalent in markdown. The equivalent is something you must choose when writing the converter, it depends on the style you want for your resulting file.

Things get complex when dealing with tags like <inheritdoc/> if you don't want to just print "Inherit from parent." like Vsxmd does or ignoring it like lontivero does.

I'm still searching for a better tool or time for improving one.

Ankylostomiasis answered 18/9, 2019 at 10:59 Comment(1)
did you find a better tool? I'm surprised docfx hasn't incorporated this already. – Mcgough
M
8

In my scenario, I wanted code documentation for my project in the GitHub Wiki, and it takes markdown files not html.

Visual Studio (Mac, in my case) has a project options > build > compiler checkbox to generate the xml documentation file for the project. Vsxmd generates one md file from this one xml file. It is very well and extensively laid out when looking at it in most markdown previewers, but GitHub seems to have low timeouts and cannot render a large markdown page.

It is not laid out as well, but something I found that GitHub can render is the single md file generated by the web tool, vsdoc-2-md.

What I ended up using for my project is Default Documentation. It is a nuget that runs during buildtime just like Vsxmd, but generates multiple md files that are small enough for GitHub to not complain.

Just note that GitHub Wiki renames files in its urls so that all .md extensions get stripped. I had to do a search/replace to strip .md from all the links in order to get clicking around documentation from the GitHub Wiki to work.

Mercury answered 31/5, 2020 at 18:42 Comment(1)
For the "GitHub Wiki" issue, see the DefaultDocumentationWikiLinks parameter. – Birmingham
B
3

Yes, it is possible. The available solutions did not suit my needs, so (disclaimer) I've started developing my own: MarkDoc.Core.

This is a standalone application, so no NuGet packages are involved. Moreover, the application is fully customizable allowing you to export to other sources than Markdown and more.

Again, this is my project and at the time of writing this answer, it is still in progress.

Burnoose answered 2/12, 2021 at 20:11 Comment(0)
K
0

The NetDocsProcessor package may potentially be an option. There is a demo project showing how the markdown files can be generated. Converting internal xml to markdown can be done with the help of ReverseMarkdown

There is no <inheritdoc /> support so far though.

Kestrel answered 7/4, 2023 at 16:31 Comment(0)
O
-8

Of course it is possible to generate markdown from XML comments. The obvious question is: Why? The best answer is: to generate a website from the markdown content.

DocFX is essentially the replacement to Sandcastle. I'm using it to generate a documentation website from XML comments in C# code.

Outlander answered 24/4, 2018 at 6:23 Comment(12)
Do you add the Nuget package (Docfx) to the project being documented? I don't like the idea of this as my domain model should be isolated. – Castalia
No, you would create a separate project, e.g. a class library, to house the documentation, or you could just call the docfx console tool separately from a build script, which is what I do. It's all on the website. – Outlander
Thanks. Does that mean that everytime you compile your project e.g. Domain Model, then it builds the documentation? – Castalia
Yes, you could get it to do that. Whether you'd want to is another question. You don't want to slow down your development waiting for documentation to build, so ideally you'd want to add another solution configuration which builds the documentation, and have that project not build in the Debug configuration. – Outlander
Finally, should the XML documentation be contained in .html files (in the _site folder) or in .md files? Please note that I am specifically referring to the XML documentation. – Castalia
DocFX will turn the XML comments into .html files. – Outlander
Do I have to tick XML Documentation in the build options (in Visual Studio). Ticking it or unticking it does not seem to make a difference for DocFX. However, it does make a difference for Sandcastle. Is that right? – Castalia
Could you answer the question above? Then I will mark the answer. +1 for the hyperlink in the answer. – Castalia
It doesn't make any difference for DocFX, as the DocFX console tool parses the XML comments directly from the source code. Sandcastle on the other hand relies on the XML Documentation file to be created. – Outlander
If I am using DocFX only then I can leave it unticked? Right? I am new to this tool and what to avoid gotchas. – Castalia
Yes, you can leave it unticked. – Outlander
The reason for converting it to Markdown is so that you can check it into Azure DevOps' wiki. – Torbert

© 2022 - 2024 — McMap. All rights reserved.