TShock
TShock copied to clipboard
Automatically generate a browsable documentation center
Like other civilized projects, every build should tigger automatic building and production of API documentation for TShock & TSAPI.
- Identifying which documentation system we should go with.
- Creating a script to build said documentation. (And god let it be better than a python script as far as "can run instantly on every platform" goes).
My ideal system is a static file generator that is super easy to run that produces self contained HTML. That way, we can host it on GitHub pages and rig the build system to automatically deploy docs for each branch, just like we do with Travis builds.
I found something the other day that would have been good for this, but now I've forgotten what it was. Watch this space
Here it is. http://dotnet.github.io/docfx/
Built by MSFT, so lgtm.
I've used Doxygen for C# in the past. I assume DocFX lets us get the same functionality but Doxygen lets you write custom handlers (I've used this for documenting API routes and permissions in a ASP project derived from attributes on the method instead of slapping it in the xmldoc).
DocFx looks more flexible. LGTM.
Had a brief look at DocFx, and it's LGTM.
Marking this as WIP as we will be going with DocFX at some point in the future
Tried to get docfx working on Mac with Mono. I was able to generate the project but can't actually serve the website because it seems to want to be able to find msbuild.dll, which apparently doesn't ship with homebrew's mono.
I don't think I'm going to fight mono again, so I'll let someone else deal with this one.
DocFX still seems like a good option. Would help resolve things like #1572. Marked as pending because no one is working on this afaik