Engine Documentation Location

[BenjamenMeyer]

We need have a place where we can store VS Engine documentation.

Requirements:

• text based format
• generator tool available to make multiple formats for distribution/use
• close to the code

NOTE: This is only documentation for the Engine itself.

Types of documentation:

• Design
• Architecture
• Protocol
• HowTos

NOTE: We might hook up API documentation too for the engine itself if we decide to integrate Doxygen or a similar tool that can extract stuff from the code.

Proposed tooling - one and only one of the following:

• [ ] ReStructured Text (RST) + Sphinx
• [x] MarkDown (MD) + ???

Proposed Locations - on and only one of the following:

• [x] doc/ (NOTE: Requires moving the man pages.)
• [ ] ???

[BenjamenMeyer]

For 0.7.x let's :

• [ ] decide where it's going to go
• [ ] decide what tool set to use
• [ ] add a basic layout
• [ ] add a README on how to add entries

That way folks can start submitting PRs for it.

[evertvorster]

@BenjamenMeyer Thanks for popping this question.

Pandoc is a great utility for converting between document formats, and .rst is natively supported by Github, so you can read documents online. This is what I used to convert the htrml that went with the base layout documentation to .rst.

May I suggest using the documentation folder that is in Vega Strike Engine Source? It won't make it into the packages, but anyone that pulls the git gets all the documentation that goes with the source. You don't get much sweeter than that.

Dumping the all the design documents into a flat folder seems a little disingenuous. Would it be better to have a directory structure based on your memory map of the source, or would it be better to mirror the current file layout of the source?

[BenjamenMeyer]

@evertvorster yes, I'd like to use the doc folder, we'd just have to move the man pages.

One of the reasons I like RST+Sphinx is that you can build directory structures and relate things. Here's an example from one of my Python projects: https://github.com/TestInABox/stackInABox/tree/master/docs. The toc notation, etc are all Sphinx stuff but you can interlink between directories and files with ease.

[BenjamenMeyer]

moving to 0.9.x as we need to get 0.7.x and 0.8.x out the door