Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
MonoGame Documentation Project #2378
This next week we're going to start the documentation project for MonoGame. I'm writing this here to publicly communicate the plan to the community and get feedback.
MonoGame will use SharpDoc for generation of class reference documentation as well as organization of hand crafted documentation pages. I have put up a quick example of SharpDoc results on MonoGame here:
SharpDoc is created by @xoofx for documenting SharpDX. You can also see it used there:
The reference docs one part of the documentation process. Our goal is to surpass the quality of the existing XNA docs by including hints as to the inner implementation of the code as well as platform specific details. The reference docs should link to or include small code examples when the API usage isn't clear.
Over the next few weeks we will create some documentation examples and tasks for documenting specific classes to help guide contributors as to how to help with the process.
The docs that are hand crafted for guides, walkthroughs, detailed system explanations, example code, etc will be authored using Markdown format in a new "Documentation" folder here in the MonoGame repo. To make changes to the docs one would fork the repo and then either edit locally on their machine or via the Markdown editor built into GitHub.
The benefits of this workflow are:
An example of this in practice is how the SharpDX docs are maintained:
When we merge code into the develop branch it will kick of documentation generation for both the reference and manual docs on the build server. The docs will be an artifact of the build just like assemblies and installers.
Then periodically (maybe once a day) we will copy the docs up to the MonoGame site replacing the existing docs with the latest ones. This will all be automated.
We will probably maintain docs for each shipped release along with docs for the latest 'develop' branch.
The docs could also be compiled for offline use either thru a Microsoft Help CHM file, VS2010 style Help 2, or even PDFs. This is all functionality we would need to cobble together ourselves or add support for it into SharpDoc.
This would be a goal once we get the docs up and running online.
Ok the docs are now being built by the build server and zipped up for download as part of the artifacts:
I'm uploading the latest now:
I have some fixes to do to the style and tools, but this is in a working state for people to start writing docs.
So it has been quiet, but I am still working on things in the background.
I've almost got a SharpDoc issue resolved (xoofx/SharpDoc#5) which should allow me to build the docs for all the platforms on the build server.
About to submit a PR with some style changes to the docs which makes them nicely fit into the website theme. Check it out... it is pretty sweet:
The next issue is really one of content.
We need to make a push at implementing the reference documentation for all the classes. I'm going to make a stand and prefer no docs to low information docs... I will reject documentation PRs that don't follow the guidelines.
The bigger job is writing the non-reference docs like getting started, tutorials, system explanations, etc. I really need help in that area.
Is there a way to have enumeration fields appear in the order they were
Other types, such as Methods and Events should remain in alphabetical order.
Also, there does not appear to be a way to link directly to a documentation
I'll investigate it. Seems like it should be possible and probably the default behavior.
There is a system for that, but I haven't fixed it to work within Wordpress yet.
It may be a whole lot of work, so I'm not sure how cost effective it will
I had a thought about that the other day.
I could make the current divider between the content list and the content page only have two states... fully collapsed or fully expanded. When you clicked on a content in the listing it would collapse and show the page, when you clicked the tab it opened back up to let you select something else.
Combine that with some tweaks to fonts and stuff and it could be usable. But how many people would even use it that way?
On my Nexus S device, I can't even see or access the divider. The page
Given that very few people will try to browse the docs on a phone, I'm not
Ok... huge step tonight.
I got the TeamCity server to deploy the documentation to monogame.net automatically after every successful build of the develop branch. This means every merge can update the documentation on the website.
The deployment takes under 30 seconds and less than 10MB of data is uploaded to the server, so it is really pretty cheap. We can do dozens of deployments per day and not tax the system at all really.
We have a little bit of an issue that the documentation doesn't invalidate the cache on the browser as well as it should. Going to do some research and figure out the best policy for that.
Ok.... on the caching. I forgot I setup the webserver to aggressively cache content via the HTTP headers. I just need to change the rules for content served out of the documentation folders. Just need to turn it down to 4-8 hours or something.
Also I think it may be worth running all the documentation HTML thru a minifier tool. It would just help with serving up the docs quicker and reduce our bandwidth usage.