Support API reference documentation
GeertvanHorrik opened this issue · comments
I've been looking for the "ultimate" documentation tool and this comes close 👍
One thing I am missing is the option to generate API reference documentation based on the xml docs from the api. Maybe it can be combined with https://github.com/Geaz/sharpDox ?
Then we could integrate with disqus and the docs would be near perfect. If you want I can help out, but need to know whether you would be interested in such a thing.
- Support disqus at the bottom of the docs
- Support API reference doc generation
Ok, first things first: I'm sorry to say but Disqus is a really evil service, and I won't merge code supporting these people.
The API reference docs, that's indeed something I looked at when I wrote DocNet, but as I had just 2 weeks I left that out and used the sandcastle help file builder (https://github.com/EWSoftware/SHFB) system instead. SHFB can generate reference doc websites, like we use here: https://www.llblgen.com/Documentation/5.2/ReferenceManuals/LLBLGenProRTF/html/5F98FA8E.htm It's not easy to create reference manuals from code as a lot of different things can be integrated in the xml docs, so it's best to outsource that to something.
Looking at sharpDox it looks really nice, tho it also looks like it generates the pages on the fly in javascript... which might not be a good idea.
-
Can you explain why? Is there a different kind of service that is better but would provide similar functionality?
-
About the generation of the api docs. We could re-use the models of sharpDox but generate it in the right format (into htm) (something like /api/{version}/
This would work great for multi-version docs as well.
1: disqus is tracking users across websites with disqus enabled, bans people across all sites, among other things (logging in via a 3rd party into disqus makes them access that 3rd party system like twitter). I don't know of any other services tho. But I also don't see the necessity of a discussion page below a documentation page: who's going to monitor the contributions so they're going to be included in the page? the documentation sites I've seen with user contributions in general are a tirefire, users report issues, but they're almost never resulting in an updated documentation page.
IMHO better is to allow people to give feedback via e.g. email.
2: I don't think you realize how much work that is ;) If you look at how complex SHPB is, it's the same amount of complexity you're now going to reimplement.
-
I understand that you are against tracking people over sites, but not sure if I can call this evil (to me evil is intentionally hurting (physical or mentally) people). It's up to the users whether they want to allow the service to access their 3rd party (e.g. facebook and lots of other sites do the same to bring in SSO). The reason I am looking into something like this is because we now have Confluence and people do use the boards for questions about the docs. And private email is easy on the short term, but then the knowledge isn't being shared to other users.
-
I probably underestimate the work, but that might be a good thing ;-) I'll try to set up some manual docs with docnet first and see if it does what I need it to do. If so, I might just be stupid and try to support api docs as well.
1: but what's the end goal with adding disqus? That people have questions below a documentation page? That's not what documentation is for. If they have questions, they should go to a place outside the docs and refer back to the docs, but not have debates below the docs: that's confusing for the reader of the docs. Sometimes it might be docs are incomplete or wrong: the user then should have a way to provide feedback on that so the docs can be updated.
Another problem is that having the debate below the docs is there forever: if you update the doc page with feedback, the debate is still there. It's like having the issue which spawned a PR open forever, long after the PR has been merged ;)
2: I think what works best is simply defining a site in the SHFB gui and generate the website from there (can be done on the command line) and link to that in your docs. There's no integration like you have a class name in your own docs and it automatically links to the class definition in the reference docs but frankly I think that's very complex to do right, in an automated fashion. Easier is to generate the reference manual first, make sure the URLs don't change per run, and refer to the pages in that site in your docs if you want to link to the reference doc of a class.
Thanks for taking the time to respond. You are right about the threads in the docs, it will be there forever, which might not be what we are looking for.
I am currently writing a multi-versioning version of the docs. Still need to figure out the best way, this is what I have so far:
https://catel.github.io => redirect to /welcome, which shows a table of contents for:
Did you ever think of supporting multiple versions or do you only care about the latest?
We solved it differently: a page which contains the links to the different versions, see: https://www.llblgen.com/Pages/documentation.aspx, which then link to the docs within that version.
I think that's a better approach as everything for a version is contained and you don't get confused which version you're in, you pick one and you're browsing that documentation.
But that's exactly what it's doing :-)
Every version goes into their own /version folder with their own docs. This allows us to generate new code samples but keep old stuff intact. I do agree that it might be easier to do a single setup for the root page though.
oohh!! I misunderstood :) I thought you wanted to cram everything into a single documentation and select per page or something.
Let's close this one, I am sick & tired after migrating docs for a week. Maybe I'll pick this one up at a later stage ;-)
heh :) I'd keep it simple and look into the sandcastle stuff first, it's really easy to setup and you can generate the site on the command line (so in a script together with the docnet call).
I've started working on this in combination with SharpDox. They have a full API which can be used to create custom exporters.
I am currently writing (and testing) an DocNet exporter. This way we can generate the MD files with the reference docs. If this all works (I'll keep you up-to-date), then we could introduce a /api/** inclusion feature into DocNet and it should all work perfectly.
that would be great. Be sure to also write some docs how things work, as otherwise I have to reverse engineer how things work to write them ;)
So in short, one has to use sharpdox with that exporter, it produces files which are then includeable in the docnet.json file, so they're converted to html by docnet ?
Correct. This allows us to have the search feature + style from DocNet.
It's still a bit ugly, but here is my first attempt:
For a start it looks great but the HTML indeed needs some work. No idea if this performs at all when you have a large API but you can always uses something else of course :) Looking forward to the end result!
Implemented!