Documentation

All discussion on project related documentation including source docs, manuals, and tutorials go here.
Azamorn
Posts: 9
Joined: 22 Jun 2016, 08:42

Re: Documentation

Post by Azamorn »

I'm busy catching up with C++ and reading some ebooks so I can better understand the code in OpenMW, I've also been scanning through it to see how it all works, I'm interested in helping to add more of the MWSE functionality to OpenMW,
Documentation would be of immense help, sometimes I'm at a loss for what a piece of code is doing.
The source code could be more thoroughly commented.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Documentation

Post by Zini »

Wiki for the overall structure. Code related documentation (classes, functions) in the code.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

Zini wrote:Wiki for the overall structure.
Can't this be eventually migrated over to the repo for use in sphinx?
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Documentation

Post by Zini »

Not sure what the benefit would be. There isn't any place in the source code where we could put this. We would have to add additional "source" files just for the documentation. Of course there is then the problem that these files would be a lot less usable then the wiki (missing hyper-links and such). We would at least need a way to automatically generate/update documentation from the source and also host it somewhere. I am not opposed to such a solution but that would require additional work.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

You wouldn't put that kind of documentation into source files, that would be silly. You would just write plain old ReST documents which is similar to Wiki syntax. These files would exist under ./docs/ and sphinx would then render them into whatever format you want. They would still be readable as ReST (which is the point). The hyperlinks would remain, just point to other documents in the ReST files and sphinx will take care of the linkage when it is rendered to html or pdf. We can also link to pages in the Wiki.

Github has a hook for readthedocs.org, it will auto-generate the documents at every tag (release) including merges into master (if we want).

I've used this system for many (widely used) projects now, so it isn't nothing new.

The additional work will likely be on my end. The rest would be up to those that want to document, but at least there would be examples and placeholders in place.

Anyone that wants to update the docs would just get a github account, fork OpenMW and send PR for review just like code reviews. That way more eyes are on it to correct errors and simplifies everyone's workflow because everyone is now using the same tools.
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

That sounds very convenient, but is there any point in having any code-related documentation on the wiki then? It feels like the two would just be pretty much the same thing.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

I feel the same way, no reason to use the wiki aside from linking to it until such time as it is ported over.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Documentation

Post by Zini »

That is an interesting approach. Having all the documentation under unified version control sounds useful. Maybe we should give that a shot.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: Documentation

Post by Naugrim »

Just a side note to broaden options.
For general documentation I'd recomend Asciidoctor, it can generate HTML/pdf/pub and other formats.
It also is supported directly in github like Markdown, so you can just post the source files in a repo and view them directly.
For instance, this repo https://github.com/asciidoctor/asciidoctor.org can be seen and edited directly online, but it also gets rendered into the site http://asciidoctor.org/ on every PR.
Of course, the rendering uses github pages and the official renderer with additional options to modify CSS and other things, but it provides quite a lot with little investment.
Tels
Posts: 21
Joined: 01 Jul 2016, 18:03
Contact:

Re: Documentation

Post by Tels »

AsciiDoctor seems like someone re-invented pod (perlpod) in Ruby. So, maybe nice if you already use Ruby, otherwise it just seems to bring in a lot of new dependencies (ruby!) for little gain. :)
Post Reply