Creating a doc

Ah, it is time for you to write your first (or second or third for forty-second) document to add to this repository. We embrace you with open arms (or thoughts if you don’t prefer hugs). By now, it is assumed you have a good understanding of how repositories work.

The documentation repository is actually a submodule of the main project repository. It is found under the /docs/ folder. If you go in here, and look at the index.rst file.

You’ll see something like this:

Welcome to Avarice
===================================

Welcome to the one-stop shop for documentation on Avarice.

What is Avarice?
-----------------------------------

Avarice was/is developed by Ouroboros Creations, which was founded by a small group of seniors at Champlain College.
It is a four-player online or local couch competitive game,in which players compete to collect as much as they can. To collect (points), they must find Greed to become the embodiment of Greed and destroy the world around them. If someone else is already embodying Greed, the three other players must work together to take them down.

Using the docs
-----------------------------------

You can use these docs as a guide to develop content for the game. A good place to start is :doc:`Project Setup </engine/setup>`.

That is an excerpt from the homepage of the documentation! Cool, right?!

All of the documentation follows what is laid out in the ReadTheDocs docs and the reStructuredText primer.

  1. What kind of documentation are you writing?

Does it have to do with Unreal Engine specifically? Consider sticking it in under /engine.

Is it a tutorial about how to make a specific asset/object or something having to do with the content pipeline? /content would be a great place for it!

Maybe it has to do with the build/packaging process or Quality Assurance testing. If so, consider /builds.

Are you getting meta and using a documentation page to write documentation pages? Woof. /documentation would be a great place for that spooky 4th wall stuff.

Is your doc about team pipelines or resources? /general is probably your place to go.

  1. Making the doc

Wherever you decide to put it, unless you are making a whole new category, the folder likely already has an index.rst file. This is what tells the html file generator (sphinx) what its table of contents is and the generic details for that category.

In the category folder, you can make your very own .rst file. These special files tell sphinx that it is a file worth looking at. Go ahead and name one in an appropriate manner to what you are documenting (this document is called /documentation/creating.rst).

  1. What goes in a reStructuredText (rst) file?

First, a header. This is what appears in the sidebar and at the top of a documentation page:

This is my header
===================================

Second, add your content. Use other documents as references and the reStructuredText primer as a guideline.

Third, have fun with it! Documents are meant to be alive. Make them fun, or at least engaging, to read. Otherwise, reading them is a pain is the frickin butt.