MAMEWorld Forums - News - Re: Documentation?

> Documentation is auto-generated from the .rst files in docs/source every five
> minutes. Surely Windows has a web browser you can point at the docs site:
> http://docs.mamedev.org/
>
> > ------ There is no more Config.txt or Windows.txt... but if you run the command
> "MAME
> > -?", you still get the old normal help stuff, and the last line is "For usage
> > instructions, please consult the files config.txt and windows.txt" ... so that
> should
> > be fixed?
>
> Yeah, we should probably update the usage information to point people at the online
> documentation.

I want to be clear that I disagree with this course of action, and feel that we should bundle Windows-compatible documentation as well. Unfortunately, changing the build scripts to generate offline documentation is beyond my skillset.

For the record: I've taken this up with Vas and he complained that it's harrrd. Firehawke doesn't really want to handle it either. I also asked Micko, but he has no free time for us right now.

Let's look at this: http://forum.mamedev.org/viewtopic.php?f=14&t=300#p961
and this guy also has some advice: https://github.com/mamedev/mame/issues/3019

Problem (?): As of MAME 0.177, MAME Windows binary releases stopped including offline help (as in the old mame.txt, windows.txt, etc. or as in some forward-looking new PDF or something file). Linux binary releases at least still had the MAN files. (Windows releases has the MAN files too, but there's no native MAN file formatter included with Windows.)

Between MAME 0.177 and MAME 0.188 MAME began including the reStructuredText files (RST) "source" from which we use Sphinx and ReadTheDocs to generate http://docs.mamedev.org , thanks to mainly Micko and Firehawke. RST files read as a kind of markup and are viewable in text editors, but preferable would be for users/compilers to install Sphinx and Python and the other requisites and run "make html" or "make pdf" or "make txt" or whatever from the docs directory.

From MAME 0.189 to today, MAME doesn't even include that, just the MAN files for the Linux platform (as it has since MAME 0.176 and before). The reStructuredText files (RST) are kept in the main git repo and source packages, that is all.

-------

Possible solution 1. Add additional scripting to the build tools repo to generate offline help from the RST files, and make mandatory that Sphinx and requisites are installed to the build box that our release manager uses (which he'd have to handle at his end)

Possible solution 2. Add all tools necessary to build the docs to the build tools package. Add "docs building" to the whole project makefile, so that when you run "make", one of the things made is the docs, and that you could run "make docs" just like we do "make tools" and it would just build the docs.

Possible solution 3. Say "screw it" and point people only to docs.mamedev.org and the PDF file it generates if they really wanna read something. (I personally don't care for this solution, people run MAME on all sorts of things that aren't online.)

Unfortunately, it doesn't seem easily solvable short-term. The tools required to build the RST files into something like PDF are somewhat arcane.

- Stiletto