I've been using Swagger recently for a WebAPI project, and I like the documentation and its inclusion of the XML Documentation I put on my methods. I have various other non-WebAPI project that I'd like to generate documentation for. I know sandcastle exists, and I've used it previously, but it isn't maintained anymore. There is a fork that is maintained (the fork doesn't appear to be much of a change over the original). Additionally, it isn't the "prettiest" thing on the planet to use (or what it generates). Previously I used the output and Google promptly down-ranked me for not supporting mobile content.
Are there any other documentation generators that make modern websites that scale nicely on a desktop and mobile devices? Am I just relegated to making the documentation manually?
This is similar to How to create website from XML documentation comments?, however, that is four years old and as we all know, a lot of changes in technology in 4 years. I'm looking for current information.
DocFX makes it very easy to combine generated and manual documentation
https://dotnet.github.io/docfx/
It was developed by Microsoft for the replacement of the MSDN documentation portal, and made open source.
Related
I've been using DocFX to generate code documentation for C# and for the most part found a lot of success with it. The articles are flexible and I really like that I can use markdown to maintain them while having them live side by side with the API references. I have also already spent the time documenting walkthroughs in Markdown and building a CI pipeline.
The problem I am trying to solve is that I need to figure out a way to get my code documentation (xml comments) output to be markdown instead of html so that it can be hosted by markdown wiki solution, specifically Azure DevOps (aka TFS). Azure DevOps Wiki seems to be very similar to gh-pages from GitHub as well, so I'm interested in similar solutions that I might be able to get to work in Azure DevOps. DocFX doesn't solve this problem because the output is .html instead of markdown.
All of Microsoft's documentation is focused on writing documentation by hand. I'm interested in generating documentation based on the xml comments in the code.
It looks like its a long open request on DocFx.
This alternative solution was recommended in a couple of places that I saw XmlDocMarkdown.
A console app that generates Markdown from .NET XML documentation comments.
Or you could always go with Pandoc. Either using the stock conversion, or roll your own custom LUA filter for the conversion process.
I am looking out for developing a C# application which posts message to a ebMS3 platform using AS4. I am new to this area. Could anyone please help? Is there any third party libraries to do this easily? If not, how we post messages using AS4 from a c# solution.
I have just implemented our own AS4 solution, and it is hard task to accomplish. Especially because .NET does not support SOAP with attachments out of the box. And there is a lot background knowledge you need to know about - all the different specifications AS4 is based on. I have not been able to find an AS4 API written in .NET without it being a standalone solution as well...
First thing is to understand AS4, and a good place to start is this blog:
https://www.codit.eu/blog/2016/02/03/as4-for-dummies-part-ii-messaging-overview/
And then you will have to understand most of the EBMS3 specification:
http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/ebms_core-3.0-spec.html
That being said - it is not impossible.
I have been looking at the AS4.NET framework as Sander talks about, and it is well-written and a very good starting point for exchanging AS4 messages. I have used it as a test-endpoint.
So unless you need to incorporate AS4 directly into an existing product (which we needed to), I can only recommend using AS4.NET.
AS4.NET is also open source (and e-SENS profile conformant), so you can have a look at their code-base and let you inspire by the hard parts in AS4.
For the MIME parts I can recommend Mimekit: https://github.com/jstedfast/MimeKit
And for some of the encryption/signing stuff Bouncycastle is great: http://www.bouncycastle.org/csharp/
Not sure whether it can be used as a library, but for a project within the European Commission an open source .NET based AS4 implementation was developed. You can find it here in the EC's code repository. I don't know if there is any support on this, so if that is important you should probably consider another implementation. A list of solutions tested by the EC for conformance with their own profile of AS4 is available here (or if that link doesn't work by searching for "as4 conformance tested implementations")
Note that most are standalone applications which you connect to for executing the AS4 message exchange. Most offer different integration options, so you should be able to integrate it into your solution.
I am looking for a search engine that can be used for sites. Sometimes we dont want to use google embedded search or the complication of lucene.
I run in to these requests:
Crawl based search
Rating and ranking of content based on content types
Searching documents like pdf and docs etc..
I dont mind if it is a commercial control that we have to purchase but I would like to be able to integrate it nicely in to some of these use cases
There used to be Lucene.net. Recently the status of this project is becoming questionable (not certain of the details). Here is the site: https://lucenenet.apache.org/
Looks like you can still download the code. Probably not much development going forward.
Bob
I have used dtSearch in the past which I know has a web crawler built into it. It doesn't come with a front end control though, it's strictly a search engine. You need to write your own results control. It does have a powerful query language though that lets you score on multiple dimensions depending on how you set up your indexes. It also has a decent .NET API to work with.
I don't know that this is any less complicated than Lucene though. So then I start to wonder what complications you are hoping to avoid.
You should look at Apache Solr (built using Lucene) - it offers a RESTful interface for integrating into .NET or whatever platform you prefer. It offers all the goodies could ask for without concern for compatibility Java .NET versions etc.
You can easily integrate Solr into your .NET app using SolrNet
Does anyone know, how I can use OpenStreetMap inside my Compact Framework application? Is there a Framework or something like that? All I can find in their wiki is how to contribute to their project and to user their software to map data. But I want to use their maps to show the users location inside my own app. I could not find anything about using their web service or whatever I have to use to show their maps inside my application.
There is a project on Google Code that wants to create a .NET library for the OpenStreetMap API. The website states that there currently is an alpha release, so it might be worth checking that out: code.google.com/p/openstreetmapnet
And there are two similar projects on CodePlex as well:
osmscout.codeplex.com
gmap4dotnet.codeplex.com
Maybe those can be used in the Compact Framework as well, or you could ask the project teams to add that feature (or get involved yourself, it is opensource after all).
CloudMade provides APIs for embedding OpenStreetMap maps in many languages - but not .NET as of the time of writing. There are plain HTTP APIs for map tiles available that you could call from .NET programs, but this is of course fairly low-level.
The CloudMade APIs are designed for developers who want to embed OSM output in their projects, rather than the OSM API which is geared towards map creation, so I think you might be interested in the CloudMade stuff.
See http://developers.cloudmade.com/projects for more.
They don't appear to have any CF libraries, but the API specification is well documented, so there's no reason you couldn't integrate with it.
I've developed a CF component that can download OpenStreetMap tiles, and also plot points of interest and basic routes. Depending on your requirements, and any restrictions on licences that you're permitted to use, then it may be of use to you?
Brutile looks quite promising. It is a library designed for C# to connect to OpenStreetMap sources. (Silverlight demo available Here.
The wiki also has a listing of all .NET related pages. Of the documented projects, OpenStreetMapViewer looks like it fits your needs the best. It's designed to display a portion of OpenStreetMap within a .NET app. I'm sure at least one of these will work for windows mobile.
At my place of work I've been put in charge of creating a coding standards document. Generally we follow what FxCop and StyleCop tools report to some degree but what we really require is document that will explain when to use a convention, why and maybe even a simple example.
This could be extended in the future for other purposes as well.
The first thing that came to my mind is to have an internal wiki site that we could build up and change easily over time but I've never used a wiki-based engine before and would like some recommendations.
If possible the engine should be in C# so we're able to tweak it to our needs if required.
If you think a wiki solution is the wrong way to go about this then please give an alternative :)
Update
I've just been informed, although we do have a php server it wont be staying, so I'm afraid php-based wiki ideas are off the table.
Update 2
Could you also (if possible) let me know if any of these solutions work with Active Directory?
Cheers
Tony
ScrewTurn Wiki is an free and open-source wiki made in C# and ASP.Net. Different database back-ends can be used, like MSSQL and MySQL, but also works without any database. It has several plugins to work with Active Directory.
Mindtouch Deki
Great wiki and it's built on C# and PHP, so you can use it on Mono or .NET
It also has Active Directory integration.
Download their ready-to-use VMware image. It started using it on my own PC then moved it to the company's VMware server when they had it ready.
We keep an internal wiki at my shop that has almost all of our documentation (not just coding standards). We didn't really see the need to roll our own so we just used MediaWiki...
We use JAMWiki and love it.
It is a solid application, we have had nothing but good interaction with both the application and the developers.
The guy you maintains the code does a great job answering questions and helping users out.
Brad Abrams has published an online set of C# coding standrds:
http://blogs.msdn.com/brada/articles/361363.aspx
If you go to the starter kits section of the Microsoft ASP.NET site, you will find several wikis to download such as ScrewTurn and Flexwiki. A wiki would be ideal for your needs by the sound of it :-)
I second MediaWiki. It's not C#, but it can be a nice excuse to sneak some free software in through the backdoor.
If you guys are a Microsoft shop, though, and are using Sharepoint, it has some built-in wiki-esque functionality.
In one project that I develop, I set up one MediaWiki wiki for development documentation, and one for online help.
I even generate part of the development documentation right from source code and database.
At the shop I'm at they use a commercial package which is really good: Confluence. What's especially nice is that it integrates with LDAP/AD so that you don't need a seperate login and it's build especially with business use in mind and has lots of free plugins. We couldn't live without it.
I am confused by what you mean when you say you don't have a php server. It runs on every platform known to man. I am noticing most Visual Studio Developers don't know that PHP runs on IIS.
I would go with mediawiki It has the biggest feature set and most add-ons developed for it in case you ever need to port your data elsewhere. If you need to modify your wiki you are doing it wrong.