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

MonoGame Documentation Project #2378

Open
tomspilman opened this Issue Apr 19, 2014 · 25 comments

Comments

Projects
None yet
3 participants
@tomspilman
Member

tomspilman commented Apr 19, 2014

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.

SharpDoc

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:

http://www.monogame.net/reference/

SharpDoc is created by @xoofx for documenting SharpDX. You can also see it used there:

http://sharpdx.org/documentation

Reference Docs

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.

Manual Docs

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:

  • Docs are versioned along side the code.
  • Thru pull requests we get a chance to evaluate new and changed docs.
  • Changes to code functionality can coincide with doc changes within the same PR.

An example of this in practice is how the SharpDX docs are maintained:

https://github.com/sharpdx/SharpDX/tree/master/Documentation

Build Process

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.

Offline Docs

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.

@tomspilman tomspilman added the Docs label Apr 19, 2014

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman Apr 19, 2014

Member

I submitted the PR adding SharpDoc tools to the dependencies repo.

MonoGame/MonoGame.Dependencies#4

Member

tomspilman commented Apr 19, 2014

I submitted the PR adding SharpDoc tools to the dependencies repo.

MonoGame/MonoGame.Dependencies#4

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman Apr 20, 2014

Member

Submitted a PR with the first version of the documentation.

#2385

Member

tomspilman commented Apr 20, 2014

Submitted a PR with the first version of the documentation.

#2385

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman Apr 20, 2014

Member

Put up the latest doc generation on the site:

http://www.monogame.net/reference/

... I need to fix up the style to match the site and fix a few more bugs and we can replace the existing documentation page.

Member

tomspilman commented Apr 20, 2014

Put up the latest doc generation on the site:

http://www.monogame.net/reference/

... I need to fix up the style to match the site and fix a few more bugs and we can replace the existing documentation page.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman Apr 27, 2014

Member

Ok the docs are now being built by the build server and zipped up for download as part of the artifacts:

Latest MonoGame Documentation From TeamCity

I'm uploading the latest now:

http://www.monogame.net/reference/

I have some fixes to do to the style and tools, but this is in a working state for people to start writing docs.

Member

tomspilman commented Apr 27, 2014

Ok the docs are now being built by the build server and zipped up for download as part of the artifacts:

Latest MonoGame Documentation From TeamCity

I'm uploading the latest now:

http://www.monogame.net/reference/

I have some fixes to do to the style and tools, but this is in a working state for people to start writing docs.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman Apr 30, 2014

Member

I need to complete this next #1575, to help people contributing docs.

Member

tomspilman commented Apr 30, 2014

I need to complete this next #1575, to help people contributing docs.

@RayBatts RayBatts referenced this issue May 1, 2014

Merged

Audio Docs #2457

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 11, 2014

Member

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:

http://www.monogame.net/documentation/

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.

Member

tomspilman commented May 11, 2014

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:

http://www.monogame.net/documentation/

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.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

Ok... more tweaks to the docs are up:

http://www.monogame.net/documentation/

You probably need to refresh a few times to get the latest to get past the heavy caching we do of CSS.

I could use people testing on more browsers and reporting any issues you find.

Member

tomspilman commented May 12, 2014

Ok... more tweaks to the docs are up:

http://www.monogame.net/documentation/

You probably need to refresh a few times to get the latest to get past the heavy caching we do of CSS.

I could use people testing on more browsers and reporting any issues you find.

@KonajuGames

This comment has been minimized.

Show comment
Hide comment
@KonajuGames

KonajuGames May 12, 2014

Contributor

Is there a way to have enumeration fields appear in the order they were
defined instead of alphabetical? The order of definition can make more
sense for enumerations, such as PlayerIndex

http://msdn.microsoft.com/en-us/library/microsoft.xna.framework.playerindex(v=xnagamestudio.40).aspx

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
page, as I found when trying to link to our PlayerIndex page to provide a
comparison to the XNA page linked above.

Contributor

KonajuGames commented May 12, 2014

Is there a way to have enumeration fields appear in the order they were
defined instead of alphabetical? The order of definition can make more
sense for enumerations, such as PlayerIndex

http://msdn.microsoft.com/en-us/library/microsoft.xna.framework.playerindex(v=xnagamestudio.40).aspx

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
page, as I found when trying to link to our PlayerIndex page to provide a
comparison to the XNA page linked above.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

Is there a way to have enumeration fields appear
in the order they were defined instead of alphabetical?

I'll investigate it. Seems like it should be possible and probably the default behavior.

there does not appear to be a way to link directly to a documentation page

There is a system for that, but I haven't fixed it to work within Wordpress yet.

Member

tomspilman commented May 12, 2014

Is there a way to have enumeration fields appear
in the order they were defined instead of alphabetical?

I'll investigate it. Seems like it should be possible and probably the default behavior.

there does not appear to be a way to link directly to a documentation page

There is a system for that, but I haven't fixed it to work within Wordpress yet.

@danzel

This comment has been minimized.

Show comment
Hide comment
@danzel

danzel May 12, 2014

Contributor

I get JS errors:
On page load.
When clicking around on the left menu (Load page, click getting started)

The alignment of menu items with sub items and those without is different:
image
Default width of div.icon is 16px (sharpdoc.css:147),
But width of one with .composed (as the > ones are) is 13px (sharpdoc.css:623)
Looks like they have different height too, maybe move width/height from .sharpdoc .composed .icon to .sharpdoc div.icon ?

Contributor

danzel commented May 12, 2014

I get JS errors:
On page load.
When clicking around on the left menu (Load page, click getting started)

The alignment of menu items with sub items and those without is different:
image
Default width of div.icon is 16px (sharpdoc.css:147),
But width of one with .composed (as the > ones are) is 13px (sharpdoc.css:623)
Looks like they have different height too, maybe move width/height from .sharpdoc .composed .icon to .sharpdoc div.icon ?

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

@danzel - What browser?

Member

tomspilman commented May 12, 2014

@danzel - What browser?

@danzel

This comment has been minimized.

Show comment
Hide comment
@danzel

danzel May 12, 2014

Contributor

chrome, latest

Contributor

danzel commented May 12, 2014

chrome, latest

@KonajuGames

This comment has been minimized.

Show comment
Hide comment
@KonajuGames

KonajuGames May 12, 2014

Contributor

That's surprising. I'm using Chrome latest as well and not seeing those
issues.​

Contributor

KonajuGames commented May 12, 2014

That's surprising. I'm using Chrome latest as well and not seeing those
issues.​

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

The alignment of menu items with sub items
and those without is different:

Just fixed that one. Remember the webserver is very aggressive with caching the CSS. Refresh a few times before checking it.

Member

tomspilman commented May 12, 2014

The alignment of menu items with sub items
and those without is different:

Just fixed that one. Remember the webserver is very aggressive with caching the CSS. Refresh a few times before checking it.

@danzel

This comment has been minimized.

Show comment
Hide comment
@danzel

danzel May 12, 2014

Contributor

Error on load:
image
window.parent.$$ is undefined.

Error when clicking Getting Started:
image
subNodes.set is undefined.

You probably need the debugger open with stop on exception enabled to see these.

Will try a few force refreshes :) Edit: Yep alignment is good now.

Contributor

danzel commented May 12, 2014

Error on load:
image
window.parent.$$ is undefined.

Error when clicking Getting Started:
image
subNodes.set is undefined.

You probably need the debugger open with stop on exception enabled to see these.

Will try a few force refreshes :) Edit: Yep alignment is good now.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

window.parent.$$ is undefined.
subNodes.set is undefined.

I'll investigate those... I am getting them during debugging.

Member

tomspilman commented May 12, 2014

window.parent.$$ is undefined.
subNodes.set is undefined.

I'll investigate those... I am getting them during debugging.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

Added a new issue to help work out the outline for the manual part of the docs. See #2520.

Member

tomspilman commented May 12, 2014

Added a new issue to help work out the outline for the manual part of the docs. See #2520.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 12, 2014

Member

Ok... the bugs @danzel reported are all fixed.

Still lots of little CSS fixes I want to make, but this is pretty ready for content.

Member

tomspilman commented May 12, 2014

Ok... the bugs @danzel reported are all fixed.

Still lots of little CSS fixes I want to make, but this is pretty ready for content.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 21, 2014

Member

Just submitted #2593 which adds support for page URLs.

Member

tomspilman commented May 21, 2014

Just submitted #2593 which adds support for page URLs.

@KonajuGames

This comment has been minimized.

Show comment
Hide comment
@KonajuGames

KonajuGames May 21, 2014

Contributor

It may be a whole lot of work, so I'm not sure how cost effective it will
be to make this documentation usable on a mobile device. It is not
currently usable, and I'm not sure what a good approach would be. Or even
if people will be wanting to view the documentation on a mobile device.

Contributor

KonajuGames commented May 21, 2014

It may be a whole lot of work, so I'm not sure how cost effective it will
be to make this documentation usable on a mobile device. It is not
currently usable, and I'm not sure what a good approach would be. Or even
if people will be wanting to view the documentation on a mobile device.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 22, 2014

Member

documentation usable on a mobile device

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?

Member

tomspilman commented May 22, 2014

documentation usable on a mobile device

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?

@KonajuGames

This comment has been minimized.

Show comment
Hide comment
@KonajuGames

KonajuGames May 22, 2014

Contributor

On my Nexus S device, I can't even see or access the divider. The page
header and footer also take up a large amount of vertical screen space.​

Given that very few people will try to browse the docs on a phone, I'm not
sure if the effort will be worth it at this stage.

Contributor

KonajuGames commented May 22, 2014

On my Nexus S device, I can't even see or access the divider. The page
header and footer also take up a large amount of vertical screen space.​

Given that very few people will try to browse the docs on a phone, I'm not
sure if the effort will be worth it at this stage.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 22, 2014

Member

Yea... I was gonna focus on getting content into the docs now. If I mess with mobile there is will be strictly because i'm bored.

Member

tomspilman commented May 22, 2014

Yea... I was gonna focus on getting content into the docs now. If I mess with mobile there is will be strictly because i'm bored.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 23, 2014

Member

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.

Member

tomspilman commented May 23, 2014

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.

@tomspilman

This comment has been minimized.

Show comment
Hide comment
@tomspilman

tomspilman May 23, 2014

Member

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.

Member

tomspilman commented May 23, 2014

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.

@tomspilman tomspilman added Documentation and removed Docs labels Feb 10, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment