Add content to Wiki for available options and sample usage

[tiesont]

From #46;

The front page does a decent job of explaining what HtmlSanitizer is supposed to do, but there isn't much in the way of documentation, as far as what options are available or what method hooks are available. It would also be useful to have a handful of demonstrations for using the aforementioned items.

I am planning on culling examples from the issues list (or determining which options could benefit from examples based on the questions I see asked most often) and/or from the test class.

Tasks:

• Add grid (or similar) of available options
• Add grid (or similar) of methods which can be overridden
• Add examples for each of the options/method overrides
• Add Frequently Asked Questions topic

Please add or suggest any other tasks that make sense for this issue.

[304NotModified]

Please also add a FAQ

Possible Content;

• How to intercept/change the sanitizing
• Why the format of the result is different (e.g. close tags)
• why AngleSharp pinned: AngleSharp constantly introduces breaking changes, see is the nuget package dependancy on anglesharp correct version #78, Error using Sanitize after updating AngleSharp to 0.9.7 #76 , Sanitize throws MissingMethodException #68, Incompability with AngleSharp 0.9.5 #64 and System.MissingMethod exception with AngleSharp 0.9.4 #53

[mganss]

1. One thing that keeps cropping up is the issue of how to deal with non-HTML that looks like HTML (see e.g. Allow Non HTML tags #91, Only sanitize denied tags/attributes - everything else is ok #103). So that could be a topic for the FAQ.

2. API documentation could be an extra page, generated from the documentation XML in the source (possibly even as part of the AppVeyor build). There are a number of tools that generate Markdown from /// comments, e.g. https://github.com/lijunle/Vsxmd

[tiesont]

@mganss The Markdown from VSXMD isn't awesome, but it isn't awful either: https://github.com/tiesont/HtmlSanitizer/wiki/API - might work as a starting point. I'm looking for alternatives, too. For instance, simply using the XML as-is and applying an XSLT might be less work and/or produce a better output.

Some of the wiki content will duplicate what's in README.md - will that page be getting simplified if the same content is in the wiki?

[mganss]

Yes, particularly the listing of all the whitelisted elements, attributes etc. should be delegated to a wiki page. IMO there should only be an intro paragraph plus the quick start usage one.

@tiesont If you could come up with such an XSLT or another solution that'd be awesome. There's also this: https://gist.github.com/lontivero/593fc51f1208555112e0

[304NotModified]

another option is of course using SHFB. You could run it on AppVeyor.

[mganss]

I've played a little with Sandcastle: https://github.com/mganss/HtmlSanitizer/wiki
Had to manually fix image paths on the home page. There are lots of warnings still when building from the Sandcastle GUI.

[304NotModified]

You could also output as HTML and setup a github page.

[304NotModified]

But of course the topic was wiki ;)

[tiesont]

There are lots of warnings still when building from the Sandcastle GUI.

That seems about right, from my previous experience. That was a while ago, though, so I'm a bit surprised.

I liked the idea of an XSLT on the XML docs, but the more I thought about it, it seems like that would only work as a stand-alone document - I can't say if I've ever embedded an XML doc with a transformation applied to it.

[tiesont]

I went ahead and chucked the Markdown that SHFB built into the wiki on my fork - https://github.com/tiesont/HtmlSanitizer/wiki - it isn't blowing me away, but that's not really what I intended anyway. Is it worth fixing the mixing documentation warnings, and then shoving those files into an API topic?

I'm going to try to make a push to have something useful on my copy of the wiki by the end of the coming week, and then you can weigh in on whether I'm heading in the right direction.

[tiesont]

An example of a wiki I'd like to emulate: https://github.com/warden-stack/Warden/wiki

[tiesont]

For the API topic, do you want a single wiki page, with all of the public types and method signatures, or should I work on making something like the SHFB output work? Doing the latter might require going through the code and making sure all of the XML comments are present and normalized, since SHFB doesn't seem to like the comments as they exist now.

[tiesont]

Apparently, pull-requests are not an option for wiki content. If you want to review what I have to far, and either pull it in or let me know what needs fixing, I'd appreciate it.

The one thing I haven't filled in that I really want to get done is the Examples topic.

[mganss]

🆗 I've pulled it in.

Regarding API docs: if you can make the Sandcastle output work, that'd be great.

[tiesont]

Haven't forgotten about this, just haven't had a ton of free time lately.

For the examples topic, does it make sense to cherry-pick content from the test suite? Otherwise, if someone has the time, maybe they could label questions/issues that they think would make good use cases for an example?

Same, I suppose, for the FAQ - I don't mind writing the content, I just don't know how much time I will have to mine the issues list and/or Stack Overflow, and maybe you've noticed patterns to the type of questions that get asked repeatedly?

[tiesont]

I've add a few examples to the Examples topic - does that format work? Or, would you prefer the examples be more complete (basically, follow the format of the test suite)?

[mganss]

Looks good 👍 I think it's unnecessary to follow the arrange-act-assert pattern in the examples, but for some examples it might be a good idea to show what the sanitized output looks like. In these cases, you could simply use a comment:

var content = @"<p>This image is self-closing: <img src=""some-image.png"" /></p>";
var html = sanitizer.Sanitize(content, formatter);
// -> <p>This image is self-closing: <img src="some-image.png" /></p>

[tiesont]

Well, the nice thing about AAA is that it's pretty clear what's going on. I was thinking of doing something along the lines of your suggestion, so I'll keep that in mind as I add more samples.

[tiesont]

@mganss I'm not sure when I'm going to be able to work on adding more examples, or updating the existing wiki content with respect to any API changes since April - should this issue be left open?

[mganss]

IMO this can be closed.

[304NotModified]

Not sure if it followed it,

will https://github.com/mganss/HtmlSanitizer/wiki/API be updated "automatically"? (script or something) Or do we need to update it manually?

[mganss]

Not from AppVeyor, though that would be cool. Can you add this, @tiesont ?