User Documentation

Anything related to PR, release planning and any other non-technical idea how to move the project forward should be discussed here.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

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

Re: User Documentation

Post 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. ;)
User avatar
Atahualpa
Posts: 1176
Joined: 09 Feb 2016, 20:03

Re: User Documentation

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

Re: User Documentation

Post 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.
User avatar
scrawl
Posts: 2152
Joined: 18 Feb 2012, 11:51

Re: User Documentation

Post by scrawl »

What is the advantage over doxygen?
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

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

Re: User Documentation

Post 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. :)
Post Reply