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 »

Really cool :o
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 »

OK, I think I've nailed it, waiting for builds to come back green and I'll merge it in.

Things I've done:
* re-organized our documentation layout into our 3 main sections: user manuals (OpenMW-CS Manual), reference materiel (Modding reference), source documentation (openmw, opencs, esmtool, etc.)
* allow sphinx to build without need of doxygen/breathe/cmake, this should simplfy the process of adding documentation
* tried to make our indentation 4 spaces (instead of 2 or 3) and be consistent across all files.
* added 3 additional areas for openmw source documentation.

Updated; merged. :)
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 »

User avatar
Atahualpa
Posts: 1176
Joined: 09 Feb 2016, 20:03

Re: User Documentation

Post by Atahualpa »

Great work, psi29a! :)
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

psi29a wrote: * re-organized our documentation layout into our 3 main sections: user manuals (OpenMW-CS Manual), reference materiel (Modding reference), source documentation (openmw, opencs, esmtool, etc.)
* allow sphinx to build without need of doxygen/breathe/cmake, this should simplfy the process of adding documentation
* tried to make our indentation 4 spaces (instead of 2 or 3) and be consistent across all files.
* added 3 additional areas for openmw source documentation.
psi29a wrote: * re-organized our documentation layout into our 3 main sections: user manuals (OpenMW-CS Manual), reference materiel (Modding reference), source documentation (openmw, opencs, esmtool, etc.)
Great, I felt the naming scheme to this point was somewhat misleading, but I suppose that's because the scope of our documentation has changed a couple times.
psi29a wrote: * allow sphinx to build without need of doxygen/breathe/cmake, this should simplfy the process of adding documentation
Hooray! This shortens my documentation for dummies guide by several paragraphs.
psi29a wrote: * tried to make our indentation 4 spaces (instead of 2 or 3) and be consistent across all files.
Ugh, thank you, I'm glad we have the same ideas about the appropriate use of spaces and tabs.


Overall, thank you very much. This should help expedite documentation in the future!
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

Ravenwing wrote:
psi29a wrote:
psi29a wrote: * tried to make our indentation 4 spaces (instead of 2 or 3) and be consistent across all files.
Ugh, thank you, I'm glad we have the same ideas about the appropriate use of spaces and tabs.

Overall, thank you very much. This should help expedite documentation in the future!
Since we are on the topic of format, may we discuss line-wrapping?
The style in the GitHub repo recommends keeping a paragraph in a single line. But I have been using the opposite approach for some time and I can hardly find any advantage in the single line approach.
I found some references that even recommend the later in Sphinx or RST: http://rhodesmill.org/brandon/2012/one- ... -per-line/
User avatar
Atahualpa
Posts: 1176
Joined: 09 Feb 2016, 20:03

Re: User Documentation

Post by Atahualpa »

Naugrim wrote:Since we are on the topic of format, may we discuss line-wrapping?
The style in the GitHub repo recommends keeping a paragraph in a single line. But I have been using the opposite approach for some time and I can hardly find any advantage in the single line approach.
I found some references that even recommend the later in Sphinx or RST: http://rhodesmill.org/brandon/2012/one- ... -per-line/
I don't really understand: Do you want to abort the single-line convention for the source code or for the actual text which is displayed? (I suppose you meant the first one.)
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 »

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

Re: User Documentation

Post by Ravenwing »

My thoughts are it's really easy to make adjustments to hard wraps in coding because most commands terminate before the 80 or 120 character limit. However, since most documentation will consist of prose, it is a lot more difficult and time consuming to have to fix paragraphs later on. Even if Sphinx is able to parse the paragraphs properly, when I'm editing, I don't want to follow weird line breaks. I read your link Naugrim, and I'd never heard of semantic linefeeds before. I do rather like the idea, so consider me about 60% convinced. However, the fact still stands that any editor I can think of allows you to enable soft-wrapping, completely eliminating the need to ever bother with trying to decide where it is logical to place line breaks. I will admit that it's annoying in GitHub to compare differences, but it's supposed to be possible for GitHub to soft-wrap in prose documents. Does anyone know how to enable this? I tried searching Google but didn't come up with anything.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

One last request psi29a related to this commit. Is there some way of suppressing the autodoxygen errors I'm getting. There's about a thousand (give or take ;) ) errors that look like this:

Code: Select all

.. autodoxygenfile:: engine.hpp
    :project: openmw
E:\Users\Ryan\Documents\PyCharm\openmw\docs\source\source\openmw\index.rst:23: ERROR: Unknown directive type "autodoxygenfile".
I don't want other errors to get lost in this and to prevent future people from freaking out. If it's not relatively trivial, I guess don't worry about it, but it would be much appreciated if you can get it to work.

UPDATE: The errors only pop up once in PyCharm and after the initial build, they don't pop up anymore. I'll leave this post here to remind myself to make note of that in my docs guide.
Post Reply