Day 14

SharpDoc

I ended up choosing SharpDoc to build SharpNav’s documentation. The choice was pretty much arbitrary. I figured I’d probably have to make some modifications to either one. So I dove right into SharpDoc’s source, figured out how to build a proper config.xml and also the proper command-line options to build it.

It’s live right now at sharpnav.com/docs!

I ran into a few issues while working with it, all of which I submitted back to xoofx’s repository as pull requests.

• There isn’t a NuGet package, so I opened a GitHub issue asking if the original author would maintain one.
• I’m writing release notes for each new version of SharpNav that gets released. I named these files as their versions (v0.9.2.md for example), but the permanent links that were being generated were incorrect. It was looking for v0.htm instead of v0.9.2.htm.
• Every single page for a class or method would bring up a javascript alert box saying the F# brush file was missing. There was a recent-ish pull request that added support for F#, but seemingly forgot to add the file that it referenced in the diff. So I found it online under a permissive (WTFPL) license and added it in.

I’ve still got quite a bit of work to do on the docs, but mostly creating my own style for it that incorporates the SharpNav logo and everything. I’d also like to see URLs being updated when pages are clicked on as well as smoothly loading new pages. Both of those are changes I’d contribute back to SharpDoc.

I’ve also been thinking that on top of SharpNav’s usefulness as a library for pathfinding and navmesh generation, it could also be very useful as an example of how to maintain a project. Or at least it could once I get all my ducks in a row with documentation and moving things around.

• I follow Semantic Versioning 2.0.0
• I have unit tests (though they are seriously lacking)
• I’ve got a website for the project published through GitHub Pages
• I have the beginnings of a Wiki
• I have CI (continuous integration) running for every commit on Linux via Travis CI and (shortly) on Windows via AppVeyor.
• All of my source code is properly licensed
• Major contributors are credited in the copyright
• It’s got an up-to-date package on NuGet
• Most of the code is documented

Given how much time I’ve sunk into reading about all of this, especially the minutae like proper methods of package restore on NuGet, I think it’s a great project to model after in terms of project structure. It’s far from ideal, but it’s better than a lot of other repos I’ve seen out there.

This might also be the foundation of a cool RCOS talk about maintaining projects and basically all the other useful things that you should be doing with your repository that isn’t writing code.

Originally published at 100daysofhacking.com on January 8, 2015.