Documentation

All discussion on project related documentation including source docs, manuals, and tutorials go here.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: Documentation

Post by Naugrim »

I don't try to sell anything ^^'' I am just passionate about the project. So let me explain a bit more.
Tels wrote: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. :)
I really don't see the relationship other than using '=' to indicate a heading, and that's it, other types of block use a total different syntax. AsciiDoc (the language) was first implemented in Python a loooong time ago and mostly abandoned by it's creator, later on the Ruby implementation appeared and with it Asciidoctor, the render engine.

It is true that it introduces the Ruby dependency, but many programs today depend on many tools and languages. Setting a self-contained environment with a Ruby machine and the proper library ('gem' in ruby terminology) in Linux/MacOs is trivial and takes 3 commands (true! check rvm). Doing so for instance in TravisCI is trivial, this allows to render a page on every PullRequest in github.
Asciidoctor is very popular in the Java community and is used in some important projects, and most people don't even know it runs on Ruby because it uses the jRuby engine to run, there's even a JavaScript implementation for those that prefer that too. This live demo uses that https://asciidoclive.com/edit/scratch/1.

If someone still things is similar to tools like perlpod, just check the quick reference http://asciidoctor.org/docs/asciidoc-sy ... reference/, or the full manual http://asciidoctor.org/docs/user-manual/. Only the length of features is enough to see is no simple tool to just do simple tech documents.

Lastly, editors like Manning or O'Reilly allow to use it, and the Linux Kernel documentation is moving also into using it.

Apologies for the ad.
TL;RD;
It's nothing like perlpod, lots of other features and you don't need to worry about Ruby because it's a)trivial to install or you can use Java or javascript.
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 »

I have a work-in-progress branch going on here:
https://github.com/psi29a/openmw/tree/sphinx/docs

this is a port of what I've already done for datadiver since it fits about 90% of our use-case. I even have it tied into a temporary readthedocs account.

http://openmw-test.readthedocs.io/en/sphinx/

There is still more work to be done of course and the cmake integration will fall away so it no longer is a requirement. I was using to pull in the version information, sadly we can't use this on RTD.

This is just a friendly reminder that I am working on it. :)

If you would like to write documentation, just go here:
https://github.com/psi29a/openmw/tree/s ... inx/source

and create a new rst file and have at it. :) To link it into document generation, just type the name of the new rst file into the toc section of index.rst
aesylwinn
Posts: 243
Joined: 14 Dec 2015, 20:30

Re: Documentation

Post by aesylwinn »

That looks pretty professional. I think it shows a lot of potential. :D
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

psi29a wrote:I have a work-in-progress branch going on here:
https://github.com/psi29a/openmw/tree/sphinx/docs

this is a port of what I've already done for datadiver since it fits about 90% of our use-case. I even have it tied into a temporary readthedocs account.

http://openmw-test.readthedocs.io/en/sphinx/

There is still more work to be done of course and the cmake integration will fall away so it no longer is a requirement. I was using to pull in the version information, sadly we can't use this on RTD.

This is just a friendly reminder that I am working on it. :)

If you would like to write documentation, just go here:
https://github.com/psi29a/openmw/tree/s ... inx/source

and create a new rst file and have at it. :) To link it into document generation, just type the name of the new rst file into the toc section of index.rst
Awesome! I'll check it out and get going right away.

How are we going to divvy this up and keep track of who is working at what? Should there be a separate post where we keep track of what's going on or maybe a wiki page? It seems like a good idea so we don't write the same thing two or three times. Or I could just update the first post in this topic

I'm guessing that last link is supposed to be https://github.com/psi29a/openmw/tree/s ... ocs/source ? :)
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're right, it changed since a few hours ago. ;)

Feel free to work on it how you like. I'm just getting the framework in place at the moment.
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

psi29a wrote:You're right, it changed since a few hours ago. ;)

Feel free to work on it how you like. I'm just getting the framework in place at the moment.
Sounds good! I'll start working on it this weekend then
nif
Posts: 14
Joined: 14 Apr 2015, 03:11

Re: Documentation

Post by nif »

Hey @DavidD another option is to simply write a new thread post here on the forums (like a blog post) about what you learned while researching and combing through the source code. Would love to see a more recent overview of the game's architecture and all of the great work done by the team. Please write it :)
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

nif wrote:Hey @DavidD another option is to simply write a new thread post here on the forums (like a blog post) about what you learned while researching and combing through the source code. Would love to see a more recent overview of the game's architecture and all of the great work done by the team. Please write it :)
Sounds fun! Also sounds like a motivator for me to get some work done. I haven't worked on this at all as much as I would have wanted because I had a one-week trip away from home, and I also just moved into a new apartment, so it's been at a bit of a standstill for a while.

If someone is used to Sphinx and/or graphviz, I'd like to automatically generate and embed call graphs for specific functions and classes, is this possible?
Tels
Posts: 21
Joined: 01 Jul 2016, 18:03
Contact:

Re: Documentation

Post by Tels »

Naugrim wrote:I don't try to sell anything ^^'' I am just passionate about the project. So let me explain a bit more.
Tels wrote: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. :)
I really don't see the relationship other than using '=' to indicate a heading, and that's it, other types of block use a total different syntax. AsciiDoc (the language) was first implemented in Python a loooong time ago and mostly abandoned by it's creator, later on the Ruby implementation appeared and with it Asciidoctor, the render engine.
Uhm, so that doesn't really inspire confidence (the "abandoned and then later reimplemented in a different language" :)

What I meant with the similiarity was the "it is easily read and written by humans, but can be parsed by machine." Since POD already fills that niche well, I'm still unsure what AsciiDoc brings to the table.

Maybe the point that most pod2X converters are still quite horrible? That would be a point for it.
It is true that it introduces the Ruby dependency, but many programs today depend on many tools and languages. Setting a self-contained environment with a Ruby machine and the proper library ('gem' in ruby terminology) in Linux/MacOs is trivial and takes 3 commands (true! check rvm). Doing so for instance in TravisCI is trivial, this allows to render a page on every PullRequest in github.
Asciidoctor is very popular in the Java community and is used in some important projects, and most people don't even know it runs on Ruby because it uses the jRuby engine to run, there's even a JavaScript implementation for those that prefer that too. This live demo uses that https://asciidoclive.com/edit/scratch/1.

If someone still things is similar to tools like perlpod, just check the quick reference http://asciidoctor.org/docs/asciidoc-sy ... reference/, or the full manual http://asciidoctor.org/docs/user-manual/. Only the length of features is enough to see is no simple tool to just do simple tech documents.

Lastly, editors like Manning or O'Reilly allow to use it, and the Linux Kernel documentation is moving also into using it.

Apologies for the ad.
TL;RD;
It's nothing like perlpod, lots of other features and you don't need to worry about Ruby because it's a)trivial to install or you can use Java or javascript.
Although I half joked, we actually have a (single) dependency on a ruby gem in our work environment, and boy, it has been quite a pain over the years.

Every now and then the process (which is used in a single automated step) breaks, due to some updates to Ruby, or the gems, or the Ruby libraries, or whatever. It always takes some fiddling re-installing or re-enabling the gem on the build machines, especially because the error is different each time and you have to google how to solve it again.

It doesn't really help that you have to sometimes install it from a Debian RPM, and sometimes from the environment inside Ruby - which makes automating the update across machines difficult. Today everyone seemingly has to re-invent packaging of their libraries in their own environment, breaking the conventions already done by the OS.

Meanwhile, we have Perl and Bash scripts, and C programs that work the same since almost two decades - unchanged :)

So, in the end, I'm not a fan of Ruby and other's who re-invent the packaging (like Node, and Bower, and hundreds of others "oh lets create our own package management, badly". I guess. Just wanted to share my experience, of course, everybody likes something else. :)
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

I got my work up on my fork of OpenMW, under the branch sourcedocs. I'm using openmw/docs/source as my working directory.

Here's a link to my fork and branch if you want to check it out. It's very basic so far, but at least I got something written down. This also opens up the possibility for feedback and help from you guys!

I'll be unable to work on it this weekend though, as I'm going to be travelling a bunch. I'll be trying my best to work on it at least 3 hours per week, excluding weekends.
Post Reply