Documentation tools setup (Sphinx, Sweave etc.)

7 replies [Last post]
Paras's picture
Offline
Joined: 07/31/2009

Is there a description of how to setup documentation tools??

Color coding looks good. Is there any way we could add openMX key words (function and parameters) to the list of recognized key words. These could be displayed in a different color.

tbates's picture
Offline
Joined: 07/31/2009
Can the documentation make

Can the documentation make links to the demo files etc.

so for instance at here it would be really helpful for people trying to use the help online if, for example, in the statement below, the .R file was hyperlinked:

The example starts with the ACE model and includes one submodel, the AE model. It is available in the following file:

UnivariateTwinAnalysis_MatrixRaw.R

Jeff's picture
Offline
Joined: 07/31/2009
The User Guide has been

The User Guide has been created with Sphinx. You can find install information here:

http://sphinx.pocoo.org/

When you svn co, the docs directory comes down with it. From there, you can explore the source or build it yourself with the make file in that directory (docs).

I've been working on the keyword issue. I would also like to link them to the Rdocs.

Was there a specific build issue you were wondering about?

Paras's picture
Offline
Joined: 07/31/2009
Thanks, I just had not set it

Thanks, I just had not set it up.

I was not sure if it required any sepcial configuration for working with R documentation - mostly due to my ignorance of LaTeX, sweave and R-documentation.

If I understand correctly, Sphinx does not care, as long as the docuement is properly structured??

Jeff's picture
Offline
Joined: 07/31/2009
Oh, OK. You need a machine

Oh, OK. You need a machine with Python, Sphinx, and LaTeX. There's an email I sent out several weeks ago with links. If you don't have it, I'll pull it up and forward it again (or put it on the wiki).

You can look at the source, for example, here. You can see that that Sphinx uses ReST (restructured text) as its input and recognizes R code with the line

.. code-block:: r

If you want to write official R documentations, that's a different story. See "Writing R Extensions".

Paras's picture
Offline
Joined: 07/31/2009
Hi Jeff, Could you please

Hi Jeff,

Could you please forward the email to me? I can't find it.
I have Python install and I believe I installed sphinx.xx.egg as well. However it is not configured correctly. Sphinx-build is not recognied during "build pdf/hrml". thanks,

Jeff's picture
Offline
Joined: 07/31/2009
I pasted it here for your

I pasted it here for your perusal:

http://openmx.psyc.virginia.edu/wiki/sphinx

Paras's picture
Offline
Joined: 07/31/2009
Additional issues with

Additional issues with html/pdf.

I was able to setup python/sphinx correctly. (I just needed to add a path to "c:\python\scripts").

I was able to "make build" and "make install" without problems. On "make html" the only way I was able to produce documentation was by changing the makefile as follows:

html:
#build
#rm -f build/$(TARGET)
cd $(RBUILD); unzip *.zip
mv build/OpenMx/html build/html
cp build/html/* docs/source/static/Rdoc
cd docs; make clean; make html

With the above setup, "make html" produced errors (log attached). However, nice html output was indeed produced in "openmx/docs/build/html"

On "make pdf" there was a "fancyverb error" (openmx) but a nice pdf document was produced in
openmx/docs/build/latex.

I am not sure if this is a problem with my specific Windows setup or if there are differences between linux/windowsow in how make/build process works.

thanks.

AttachmentSize
sphinx-err-khnzy2.log_.txt 7.81 KB
OpenMx.log_.txt 39.49 KB