openmw.org

What about my makefile? I have a makefile that builds the various formats (for now HTML, LaTeX, manpage and PDF):
https://gitlab.com/HiPhish/OpenMW-CS-ma ... r/makefile

Since I am not writing a series of tutorials I think ./docs/manuals/ would be a better place. I'll try to get a PR up later today, then we can discuss such details there.

EDIT: I'm browsing through some of the links you posted, it's interesting to see how real projects do it. I'll see what I can replicate from those.

I don't see a problem with images (as long we are not blowing up the repo size so much that github is becoming angry with us).

Committing the makefile is fine. If it is platform-independent it is definitely useful. If it isn't commiting it still won't hurt.

About docs/manuals: Well, I have rambled enough about how I feel about people calling tutorials manuals. I would really prefer if you would not do that. Both the locations psi29a and I have proposed would be okay.

PR is up:
https://github.com/OpenMW/openmw/pull/891

I am now using Sphinx rather than a self-rolled makefile, that gives us more fancy output. Sphinx supports C and C++ as well, but it cannot grab the code documentation from the source files out of the box like Doxygen can (it can do that for Python though). If depending on Sphinx is not acceptable I can revert back to just reST, it's your decision.

I <3 sphinx and I can wire it up to do the autodoc with C++ if necessary... I've done it before!

Example:
https://github.com/psi29a/datadiver

Thank you for this!

Sorry for disappearing for almost a year, I have just updated the pending PR. I see someone else has been adding, what is the status of that? Is there a discussion thread going on? I couldn't find any.

Discussion is going on in the github MR/PR itself.

Some tutorial on sphinx would be nice.

sirherrbatka wrote:Some tutorial on sphinx would be nice.

Do you mean instruction on the syntax? If so, I think the quickstart guides should be sufficient for most purposes. The Sphinx ones are:
http://www.sphinx-doc.org/en/1.5.1/rest.html
http://www.sphinx-doc.org/en/1.5.1/markup/index.html

The ReST one is:
http://docutils.sourceforge.net/docs/us ... ckref.html

I like the ReST one for most purposes.

If you mean on getting Sphinx set up on your computer, I'm currently writing a tutorial on how to set everything up to be able to help with documentation. I should have a bit of extra time over the next couple of weeks so I'm hoping to begin writing some more again.

@psi29a, I'm probably going to need some help figuring how to get everything set up on my computer myself so I can actually write the damn thing, so prepare yourself!

This thread has the instructions I use: viewtopic.php?f=20&t=4073&p=45232#p45223

It talks about getting it running, at least on MacOS and Linux. It is more or less the same for windows, but you'll have to get used to using the CLI/CMD/terminal

sirherrbatka wrote:Some tutorial on sphinx would be nice.

Wait. Where have you been?