openmw.org

From what I've seen and read through, this is great progress.

So we have my sphinx/doxygen branch and your pure sphinx branch, now we just need to bring them together.

I was thinking to merge mine first, then yours, then I can tie in OpenMW-CS's documentation so it is all produced in one go.

Is this a plan or do you have another idea?

@Zini: what do you think?

Sounds good to me.

OK, merge request ready... just in time for 0.40

https://github.com/OpenMW/openmw/pull/1006


You can review the results here:
http://openmw-test.readthedocs.io/en/sphinx/

Once this is merged, DavidD can rebase against master to merge in his documentation.

Things right now are split into 2 categories: OpenMW (Auto-doc/doxygen) and OpenMW-CS (user manual). The general idea is that we have code documentation in one section and user manuals in another, we can always expand this later as necessary.

psi29a wrote: Once this is merged, DavidD can rebase against master to merge in his documentation.

Things right now are split into 2 categories: OpenMW (Auto-doc/doxygen) and OpenMW-CS (user manual). The general idea is that we have code documentation in one section and user manuals in another, we can always expand this later as necessary.

Great! I'm still very new to using forks, but I assume you mean rebase against master and then perform a pull request to get it merged when needed?

Sounds like a good plan to keep the code manual and the cs manual separated. This is shaping up nicely!

You got it.

Thank you for helping out! I have a feeling that once we setup the infrastructure, it will make the barrier to entry a lot smaller for those that would like to help write user manuals and guides.

This also allows anyone to write code documentation where it belongs, in the source files. We're not completely there yet, I still need to wire up the rest... but we have at least one major (mwbase) directory down.

My pleasure! I was afraid I'd be too late to do anything useful, but I like writing documentation so I guess I'm right on time

My branch has been merged in!

Results:
http://openmw.readthedocs.io/en/master/

What next, things to do:

For now, the index.rst file can be split into three sections:
* Info about OpenMW on top, this can lead into porting Wiki documents over
* User Manual's and Guides, like the OpenMW-CS manual in the middle
* Source Documentation at the bottom

If this doesn't work out or it needs adapting/changing, no problem... at least we have a system in place!

Hi!

I'm still alive! I even pushed some useful work the other day. I was planning on working more than that this week, but I just got word from the company where I'll hopefully be doing my master thesis and they would like a work sample, so I'm not sure exactly how much time I'll be able to spare. I'm going to turn it in on Friday or Monday though, so after that I'll have more time for OpenMW

I've volunteered to help out with non-source documentation but I have a few questions:

1. Is ReST more of a general concept, or is it an actual language? If it's an actual language, is this the correct reference I should be using?
2. Do we have any references for how to go about authoring documentation?
3. Do we have an official style guide for the actual content?
4. Have we decided to use American or British English?
5. If DavidD is working on source docs and I work on user docs, I doubt this will be a problem, but is there an established way of not accidentally working on the same doc and overwriting the other's work?
6. Is there anything else I need to know about standard procedures for this kind of stuff? I am skimming the wiki on what developers need to follow, but there's a lot there and most of it doesn't pertain to me, so I may miss some things.

Hi!

Ravenwing wrote:Is ReST more of a general concept, or is it an actual language? If it's an actual language, is this the correct reference I should be using?

ReST is the syntax we're using, and sphinx is the "compiler" used to turn the ReST into HTML. I use the primer available on the Sphinx website since it's nicely formatted.

Ravenwing wrote:Do we have any references for how to go about authoring documentation? Do we have an official style guide for the actual content?

Since you're not documenting the source code I don't know. I have a layout set up with some basic guidelines for the code part, but nothing else. If you don't find anything and no one says differently, feel free to write up a document on it.

Ravenwing wrote:Have we decided to use American or British English?

I consciously use British English, but since I'm Swedish I've mostly learned American English, so it might bleed through.

Ravenwing wrote:If DavidD is working on source docs and I work on user docs, I doubt this will be a problem, but is there an established way of not accidentally working on the same doc and overwriting the other's work?

We got the documentation under source control. We use Git; it helps with conflicts when two people modify the same files and also keeps track of file history, so mistakes can always be undone.

Ravenwing wrote:Is there anything else I need to know about standard procedures for this kind of stuff? I am skimming the wiki on what developers need to follow, but there's a lot there and most of it doesn't pertain to me, so I may miss some things.

Mostly just Git related things. Knowing how to fork a repository, committing, pushing, merging, and pull requests will get you far. Since the documentation is mostly unwritten, you have pretty free hands. The source documentation is located inside the docs/source folder. The "openmw" folder is currently used for the source code, and the "openmw-cs" is for the cs manual.

If you need any help or have any questions, feel free to ask here!

What are you considering writing about?