Manual & Icons

Involved development of the OpenMW construction set.
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

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.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

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.
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

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

Re: Manual & Icons

Post by psi29a »

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!
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

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

Re: Manual & Icons

Post by psi29a »

Discussion is going on in the github MR/PR itself. ;)
User avatar
sirherrbatka
Posts: 2159
Joined: 07 Aug 2011, 17:21

Re: Manual & Icons

Post by sirherrbatka »

Some tutorial on sphinx would be nice.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Manual & Icons

Post by Ravenwing »

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

Re: Manual & Icons

Post by psi29a »

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 ;)
User avatar
lysol
Posts: 1513
Joined: 26 Mar 2013, 01:48
Location: Sweden

Re: Manual & Icons

Post by lysol »

sirherrbatka wrote:Some tutorial on sphinx would be nice.
Wait. Where have you been?
Post Reply