Documentation

All discussion on project related documentation including source docs, manuals, and tutorials go here.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

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?
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Documentation

Post by Zini »

Sounds good to me.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

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.
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

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!
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

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. ;)
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

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
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

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! :D
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

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 :)
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Documentation

Post by Ravenwing »

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.
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

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?
Post Reply