Fix and do regression tests for docs generation and publish pdf and epub versions

Issue #293 new
Arthur Dent
created an issue

1) Cloned source from this repository does not build epub:

$ make epub
sphinx-build -b epub -d _build/doctrees   . _build/epub
Running Sphinx v1.3.1
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [epub]: targets for 33 source files that are out of date
updating environment: 33 added, 0 changed, 0 removed
/usr/lib64/python2.7/site-packages/rpy2/robjects/packages.py:438: UserWarning: Error in loadNamespace(name) : there is no package called ‘ggplot2’

  env = _get_namespace(rname)

Encoding error:
'ascii' codec can't decode byte 0xe2 in position 580: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-jIBJje.log, if you want to report the issue to the developers.
make: *** [epub] Error 1

2) Similar for latexpdf

3) Similar for singlehtml

4) google for pdf found only old version on readthedocs

5) Building at readthedocs fails: https://readthedocs.org/builds/rpy2/

6) pypi "source" tarball does not include docs source

7) http://rpy2.readthedocs.org/en/latest/ has old version and broken link for "Edit at bitbucket". (Possible cause of build failure there?)

8) Release process needs regression tests for successful doc builds to avoid future recurence.

9) For convenience that regression test could actually "publish" online eg by triggering builds at readthedocs and verifying success. (They have hooks for this). Google searches for pdfs of docs are common.

Comments (13)

  1. Arthur Dent reporter

    Thanks that worked, now got a usable epub (with many warnings about mssing .png files for ggplot2.

    Didn't know to do that because stumbled here from urgent need to read rpy2 docs while offline in order to learn as little as possible about R while using it from python. Even finding out how to install ggplot2 when told to do so was a step I would rather have postponed learning.

    Items 4 to 9 still worth fixing as many others like me just want to be able to read the docs in a convenient form (pdf for me) and would give up and just read the html online rather than learning how to report an issue here, let alone learn how to fix trivial build problems themselves.

    Item 2 for latexpdf still broken. Gives similar warnings for ggplot2 .png files missing then:

    ! LaTeX Error: File `titlesec.sty' not found.

    Type X to quit or <RETURN> to proceed,
    or enter new name. (Default extension: sty)
    
    Enter file name:
    

    No idea what to do so just kept hitting RETURN many times before quitting.

    No additional log in tmp presumably because I aborted.

  2. Arthur Dent reporter

    10.) Confirmed that the the many warnings of missing .png files from ggplot resulted in corresponding missing illustrations in the epub I generated from current sources. Also missing from the only pdf version I was able to find online, for 2.5.0-dev created Fri 11 Jul 2014 11:15:29 AM AEST. Presumably there is some step that should be taken as part of the build documentation process to cause these figures to be generated, which does not happen automatically when ggplot2 is merely freshly installed. Also may as well include installation steps for obtaining any needed R packages such as ggplot2 when missing and any needed TeX files such as titlesec.sty when missing.

  3. Arthur Dent reporter

    Thanks, that worked after first installing R packages hexbin and maps (as well as previously ggplot2, but no others in my case). Worth including check/install of these and any others I may have already got that are not in standard minimum installation.

    So my previous "usable" epub has now grown from 425kB to 1.2MB and does look much better with illustrations.

    Still got the following warnings:

    copying static files... WARNING: logo file 'rpy2_logo_64x64.png' does not exist done copying extra files... done writing mimetype file... writing META-INF/container.xml file... writing content.opf file... WARNING: unknown mimetype for _images/inheritance-726ae5717be06870534f78af911b953713c227bc.png.map, ignoring WARNING: unknown mimetype for _images/inheritance-d9f8ba4c5be61df5ab04757d1f341d81121bb618.png.map, ignoring WARNING: unknown mimetype for _images/inheritance-b83504dff25536be70449fed5fe971cbeb8ec03b.png.map, ignoring WARNING: unknown mimetype for _static/demos/radmin.py, ignoring WARNING: unknown mimetype for _static/demos/graphics.py, ignoring WARNING: unknown mimetype for _static/demos/example01.py, ignoring WARNING: unknown mimetype for _static/demos/benchmarks.py, ignoring WARNING: unknown mimetype for _static/demos/rpyclient.py, ignoring WARNING: unknown mimetype for _static/demos/rpyserve.py, ignoring WARNING: unknown mimetype for _static/demos/s4classes.py, ignoring writing toc.ncx file... writing rpy2.epub file... build succeeded, 13 warnings.

    I am not worrying about these as I now have adequate doc for offline use.

    Likewise not attempting to fix my (Fedora 20) texlive installation to work with make latepdf. Fedora does not include tlmgr and I don't want to learn about texlive and epub is adequate substitute for pdf for my needs. I assume the absence of tlmgr makes it at least partly a Fedora 20 issue rather than an rpy2 issue (or my ignorance - I couldn't figure out quickly enough how to work out what additional Fedora texlive-* packages I should get from the huge numbers available).

    But I do recommend that ALL the necessary steps from "vanilla" installs of R and texlive in each of the options listed by "make help" should be included so it "just works" (eg "make epub" should itself do "make rpy2demo_graphics").

    Resolving all of points 4-9 in my original post would be helpful to others looking for docs before installing, especially point 9.

    BTW After reading I am still unclear whether I can hope to just learn to use R via ipython without learning much about R as a language. But I guess that is not a developer issue but for others to write about.

    Anyway, thanks for the software with docs and thanks for the help.

  4. Laurent Gautier

    The usual targets in the Makefile for Sphinx documentation are not modified because the additional target rpy2demo_graphics is creating new figuress each time each time, needed or not.

    This is not optimal, but patches or suggestions are welcome.

  5. Arthur Dent reporter

    I'm not competent to do a patch that conditionally does rpy2demo_graphics iff the required .png files are not present - though that rings a bell as what make does routinely.

    Also not competent for suggestions but perhaps creating again each time is only annoying for deveopers repeatedly doing builds who could use an alternative set of targets that do not include it, while the default targets listed by --help could just generate them whether necessary or not as that would help larger number of users unfamiliar with the make file who just want to generate docs.

  6. Laurent Gautier

    I'm not competent to do a patch that conditionally does rpy2demo_graphics iff the required .png files are not present - though that rings a bell as what make does routinely.

    It would require to be slightly more sophisticated than that, which is only build the figures if any of the source code involved to do so is more recent than the figures whenever they exist. This is precisely what make is designed to do, as you suspect it.

    Also not competent for suggestions but perhaps creating again each time is only annoying for deveopers repeatedly doing builds who could use an alternative set of targets that do not include it, while the default targets listed by --help could just generate them whether necessary or not as that would help larger number of users unfamiliar with the make file who just want to generate docs.

    The doc is rebuilt for releases only at the moment. I'd like to have continuous integration and building of the doc and automation will be need at that point. The doc will be built from scratch each time though.

  7. Log in to comment