Sourceforge is down for few days, and with it the project page or the documentation is no longer accessible.
Independent hosting should be considered....
rpy2.github.io could do the trick , couldn't it ?
It could work. So could hosting any static HTML on pypi.
I am more generally thinking about a better automated and integrated
solution including continuous integration so the limited time I can spend
on pypi is never on something that should be scripted (e.g., building and
publishing the HTML doc from the source).
As mentioned (parenthetically) in point 9 of #293 readthe docs has hooks to enable automatically triggering a build there with each release. It also allows anyone to trigger a build of epub and pdf versions as well as single page and normal html versions. This should provide both the simplest possible automated and integrated solution and a hosting location where people would naturally go to look for (or even serendipitously come across) docs in different formats.
Because later automatic build broken, currently has older version of docs but clearly has worked in past and could easily be made to work again.
BTW link back to bitbucket for "Edit on bitbucket" is also broken presumably just due to changed location since that old "latest" version (2.5}.
Presumably instructions for anyone to setup by login. I haven't looked.
Can the build environment on readthedocs have the required pieces (R, R packages, graphviz for the class inheritance diagrams) ?
@davclark worked out the initial build on readthedocs, IIRC. He may have more info about this.
There is comprehensive documentation.
My strong overall impression is that readthedocs is specifically designed to do what you want done, flexibly for any package that uses sphinx (and some other options).
My quick impression on your specific question is that you would have to list those required pieces in a requirements file as used by pip (which I gather is what should be done anyway for installation via pypi and I suspect should be added to what you currently have at pypi).
I base that quick impression with little knowledge from this description of their build process and code snippet:
*The first step of the process is that we check out your code from the repository you have given us. If the code is already checked out, we update the copy to the branch that you have specified in your projects configuration.
Then we build the proper backend code for the type of documentation you’ve selected.
If you have the Use Virtualenv option enabled, we will run setup.py install on your package, installing it into a virtual environment. You can also define additional packages to install with the Requirements File option.
When we build your documentation, we run sphinx-build -b html . _build/html, where html would be replaced with the correct backend. We also create man pages and pdf’s automatically based on your project.
Then these files are copied across to our application servers from the build server. Once on the application servers, they are served from nginx.
An example in code:
run('python setup.py install')
run('pip install -r %s' % project.requirements_file)
That page also lists graphviz (and texlive-full) as already included in the build environment because widely used by python packages, but of course not R or R packages so they would have to be included in your requirements file.
Hmm I guess pip isn't a good way to install R, although once rpy2 is built it should be able to use it with an available R to install additional R packages needed for building the docs.
This FAQ section makes me less optimistic about installing R itself:
I guess there should be some way to do a custom build environment that includes R but I wouldn't know. There is some mention of it in the docs (and advice on installing your own copy of readthedocs) but I don't understand enough to comprehend.
An obvious work around could be to produce the desired R outputs like the .png files and include them with the docs source.
If my reading of their support page is correct, this would fall under commercial support. Not something I am fundamentally against.
Finding funding for this, among other things, would be a way to achieve some independence(*) and have a better integration between general web pages for the project and the repository (e.g., automated nightly builds of the package for development versions, automated build of the documentation, better automation for releases).
I looked at this in the past, but it seemed that the chances of getting funding (for an Open Source project trying to bridge communities often meeting each other for dance-offs (or even miction contests)) seemed pretty low (and the little resource better spent on the code and documentation until the time the possibly futility of a standoff would eventually emerge).
(*: obviously this would the dependency would be on continued / sufficient funding)
I don't think your reading of their support page is correct. I think their orientation is to provide free hosting for FOSS projects and fund themselves by offering the same facilities to commercial projects for both hosting fees (with some support) and additional support fees.
Anyway, worth checking by just asking them for help as a fellow FOSS project. If they are unable to provide enough help in the free time they have available they may offer commercial support instead (or I may be wrong). Either way no reason to wait for funding before asking them, especially as you don't expect a good chance of getting funding soon.
BTW although not competent to judge, I would have thought just building all the necessary .png files and other R outputs needed by sphinx for building the documentation and including them with the source release for building documentation would be a satisfactory workaround.
Your own nightly development builds with R would simply trigger documentation builds at readthedocs whenever you do a release build - and the general web pages would just be another part of the built documentation.
Also pushable to other web servers and they even provide DNS facilities for using CNAMES to make their hosting appear to be a subdomain of yours).
Building the doc on readthedoc is back, although there are no figures (class diagrams or R figures). Looking at all the CI, doc building and hosting, etc... will happen after rpy2-2.7.0 is released.
Readthedoc is convenient, and storage is relatively cheap (that is the storage required to track dynamically generated content requiring 3rd-party tools not on the RTD site by default is abundant compared to my time).