-
Notifications
You must be signed in to change notification settings - Fork 200
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add content to Wiki for available options and sample usage #104
Comments
Please also add a FAQ Possible Content;
|
|
@mganss The Markdown from VSXMD isn't awesome, but it isn't awful either: 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? |
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 |
another option is of course using SHFB. You could run it on AppVeyor. |
I've played a little with Sandcastle: https://github.com/mganss/HtmlSanitizer/wiki |
You could also output as HTML and setup a github page. |
But of course the topic was wiki ;) |
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. |
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. |
An example of a wiki I'd like to emulate: https://github.com/warden-stack/Warden/wiki |
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. |
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. |
🆗 I've pulled it in. Regarding API docs: if you can make the Sandcastle output work, that'd be great. |
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? |
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)? |
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> |
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. |
@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? |
IMO this can be closed. |
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? |
Not from AppVeyor, though that would be cool. Can you add this, @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:
Please add or suggest any other tasks that make sense for this issue.
The text was updated successfully, but these errors were encountered: