FAQ\Reference for MonoGame - Open Discussion

41

Jjagg…

How do I set up the MG documentation files so that I can work with it using DocFx?

Do we do this using DocFx against a Git repository?

42

Sorry for the confusion :stuck_out_tongue: Currently the docs are still using the old doc generation system. I’m pushing to switch to docfx instead, but for now things have not changed. Docfx uses markdown, just like the current system, so things won’t change as to how to contribute anyway.

So to edit the docs, you still:

  • Fork MonoGame
  • Edit documentation pages in your fork (which you can do by navigating to the relevant docs page on GitHub in your fork in the browser and clicking the edit button)
  • Set up a pull request to merge your changes into the MonoGame repo

I’ll post an in-depth guide with images once I have some spare time :slight_smile:

43

I’m hosting the new docs on GitHub with GitHub Pages. Check it out: https://jjagg.github.io/MonoGame-docfx/
If there’s anything about the design you’d like to be changed, let me know by opening an issue.

There are “Improve this Doc” links on most pages, but you should not use those yet, since they link to the doc pages on my fork of MG instead of the actual doc pages (I can probably make them link to the official MG repo, will look into it).

The idea is that those pages are embedded in the docs on this website. Will look something like this:

mg-new-docs.png1920×928 63.5 KB

2 Likes
44

Looks great, Jjagg…

Is this the set of documentation that we can work with using DocFx?

I have used quite a few source-control systems and currently have a version of Subversion set up on my own server. However, I have never had the opportunity of working with a document system outside of SharePoint, which I did some development for a number of years ago.

Any guide or information you can provide me with will be greatly appreciated…

:relaxed:

45

Thanks!

Docfx doesn’t handle sharing the docs. I used Git for that.

Docfx generates HTML pages from markdown files and table of content (toc) files that specify the structure. The toc files are similar to the config.xml file used by SharpDoc.
As a preprocessor step, it can extract the public API given .csproj files and source files and turn it into markdown and toc files (that will in turn be used to generate the HTML for the final web pages).

To actually host these pages somewhere, you need to get the files generated by docfx on your server. Here’s how I did it for the MG docs:

  • let docfx generate the HTML pages in the _site folder. This folder is not added to the MG repo (I added _* to the .gitignore file). We don’t have to have it in source control because it is all generated from files that are in version control.
  • The _site folder now contains the HTML, css and JavaScript files that make up the entire website. In the root of that folder there’s an index.html file that is the landing page of the website.
  • To set up GitHub pages, all you need is a repo with the HTML/CSS/JS files and an index.html file in the project root for the landing page.
  • The next step is quite obvious. I Initialized a Git repo in the _site folder and pushed it to a new repo I created on GitHub. Then I enabled GitHub pages. That’s all there is to it.
46

The documentation on the docfx website is pretty extensive. I recommend the articles on there for more information. Or just ask of course :slight_smile: