openmw.org

Really cool

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.

Here you go!

https://openmw.readthedocs.io/en/master/

Great work, psi29a!

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!

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/

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.)

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?

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.

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:
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.