Page 5 of 5

Re: User Documentation

Posted: 17 Feb 2017, 08:31
by Naugrim
psi29a wrote:Honestly, I like a good hardwrap at 80 or 120 (your choice) characters. That way when viewing in something that doesn't softwrap, the document is still readable. The good news is that ReST (as parsed by Sphinx) doesn't care about line-wraps and will parse as a paragraph. The only way to not let ReST do that is to end your sentence with two white spaces.

You guys with me on the 80/120 character thing? :)
I think we are on the same page here, and I only talk about prose documentation.
I mentioned it because in the guide it is mentioned otherwise https://github.com/OpenMW/openmw/blob/m ... de.txt#L28

Probably, this is a much simpler explanation of the same concept: http://asciidoctor.org/docs/asciidoc-re ... e-per-line. As long as your language of choice ignores single line-breaks, it makes wonders.
Another thing to add, is that makes very easy to comment on specific lines of a PR during review.

Re: User Documentation

Posted: 17 Feb 2017, 09:11
by psi29a
Sadly there isn't much we can do, if breathe/doxygen/etc are not loaded, then the linked documents (rst files) are using sphinx directives that don't exist and will warn you about them. The good news is that once the initial build is done, any subsequent builds only looks at changed documents so you'll no longer get the warnings.

If you would like to write a sentence and then hardwrap to a new line for the next sentence (in a paragraph), be my guest! That makes it easier to read too. Some sentences can drag on though and should be avoided or broken up otherwise if need be hardwrapped on a comma or semi-colon.

Thankfully we have a lovely review process on github that allows people to comment, spot-fact-check and other wise be grammar-nazies. :)

We should avoid the comma vs. serial comma religious war. ;)

Re: User Documentation

Posted: 17 Feb 2017, 10:36
by Atahualpa
psi29a wrote:We should avoid the comma vs. serial comma religious war. ;)
Really? :cry: I consider the serial comma one of the few advantages English has compared to German. 8-)

Re: User Documentation

Posted: 17 Feb 2017, 12:26
by psi29a
Just added source documentation for openmw-cs.

Do we want to cover all our 'apps'? Do we also want source documentation for components?

For those curious about source documentation, it reads in from header (hpp) files. So if you are going to document anything, please put your documentation there.

Documentation in the cpp files is specific to the implementation of a function or object but not exposed to other modules. If it needs to be used/exposed outside the cpp file, then it should go in the header (hpp) file.

Re: User Documentation

Posted: 17 Feb 2017, 18:50
by scrawl
What is the advantage over doxygen?

Re: User Documentation

Posted: 17 Feb 2017, 19:38
by Ravenwing
scrawl wrote:What is the advantage over doxygen?
From my understanding psi29a was just telling everyone how they should be properly utilizing doxygen, but I don't work on the source docs, so not sure.
psi29a wrote:We should avoid the comma vs. serial comma religious war.
It's inevitable :lol: but we can table it for now.

If everyone else feels very strongly that we should use the semantic linefeeds then I think I can get behind it. I would prefer that to a simple character limitation and to a sentence only linebreak. We should always strive for clarity regardless.
psi29a wrote:The good news is that ReST (as parsed by Sphinx) doesn't care about line-wraps and will parse as a paragraph. The only way to not let ReST do that is to end your sentence with two white spaces.
Which we shouldn't be doing anyway.

Re: User Documentation

Posted: 17 Feb 2017, 20:23
by psi29a
scrawl wrote:What is the advantage over doxygen?
Nothing, that is why we use doxygen. :)

breathe (a sphinx plugin) uses doxygen to autogenerate docs.

There are a few differences in output generated by RTD ad doxygen:
https://breathe.readthedocs.io/en/lates ... ences.html

With a bit of work we could get them close to eachother. I, for example, love the diagrams doxygen makes. :)