New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add support for readthedocs #6
Comments
With some cajoling, and with proper support from our end, RTD might be willing to make some Sage version available on their build machines. This is still non-trivial as a project's documentation might build correctly against one Sage version but not another and Sage has no reliable API (a serious problem, but one beyond the scope of this). In the past I believe they've been willing to add non-trivial binary dependencies on their build system if there was enough demand. And if we are willing to help support that effort (as opposed to just saying "you must install Sage on your machines" and expecting them to just do it), they might be amenable. I could ask... |
Alternatively, if that proves infeasible, all of RTD's server / build system software is available and documented. A few years ago I set it up locally in order to try to fix a couple issues I had. I don't remember what went into it, and the setup has probably changed since then. But worse comes to worse we can run our own RTD instance for Sage. |
In fact, the more I think about it, the more convinced I am that we should just run our own instance. Configuring and installing Sage is not trivial, and ideally we'll want to provide any and all Sage versions a project might want to build their documentation against. This will undoubtedly spiral beyond what RTD's already overstretched support "staff" (volunteers, really) can handle. We should try setting up and maintaining our own instance for Sage, and only bother them with specific issues with running our own RTD server as they occur. Perhaps William would be willing to help provide hosting for such a site.... |
On Mon, Jan 16, 2017 at 05:43:30AM -0800, Erik Bray wrote:
In fact, the more I think about it, the more convinced I am that we
should just run our own instance. Configuring and installing Sage is
not trivial, and ideally we'll want to provide any and all Sage
versions a project might want to build their documentation against.
This will undoubtedly spiral beyond what RTD's already overstretched
support "staff" (volunteers, really) can handle. We should try setting
up and maintaining our own instance for Sage, and only bother them with
specific issues with running our own RTD server as they occur. Perhaps
William would be willing to help provide hosting for such a site....
Thanks Erik for the feedback! Very informed as usual :-)
|
Perhaps I'll go ahead and try setting up a RTD server on our OpenStack infrastructure and see how it goes. (Unrelatedly, I finally figured out how to get to their helpdesk, and have asked them to open the remote management ports needed for Windows; we'll see what they say...) |
On Mon, Jan 16, 2017 at 08:19:50AM -0800, Erik Bray wrote:
Perhaps I'll go ahead and try setting up a RTD server on our OpenStack
infrastructure and see how it goes.
(Unrelatedly, I finally figured out how to get to their helpdesk, and
have asked them to open the remote management ports needed for Windows;
we'll see what they say...)
Cool!
|
It would be easy to extend the Travis CI scripts so that they deploy the built documentation to github pages (see #8) |
@embray I think making all of sage available on the RTD server just so we can build the documentation of sage packages is extreme overkill. The part of sage that is needed in order to build the documentation is actually really small. If we would want this then we should put the relevant documentation building code of sage in a separate python package on which but sage and sage packages can depend for documentation building. |
On Tue, Sep 05, 2017 at 02:12:22PM -0700, Maarten Derickx wrote:
***@***.*** I think making all of sage available on the RTD server just
so we can build the documentation of sage packages is extreme overkill.
The part of sage that is needed in order to build the documentation is
actually really small. If we would want this then we should put the
relevant documentation building code of sage in a separate python
package on which but sage and sage packages can depend for
documentation building.
Just as a data point in this direction: in
https://github.com/sagemath/more-sagemath-tutorials/, the
documentation is built by Sphinx on RTD, with support of a certain
number of the Sphinx features for Sage's documentation (cross
references to Sage and Python's documentation, special roles, ...).
What made it easier is that, by nature, this repo consists mostly of
ReST files. Where things become harder is when documenting a module
where a lot of the documentation resides in the source files. Which
requires Sphinx to import them in the first place. Which in turn
breaks if Sage is imported but not available.
One workaround would be to create a fake sage module, faking all the
submodules sage.** and their content. At some point last Spring, I
pondered whether one could create in Python a fake module "foo" which
would lazily generate fake submodules (and fake functions/classes/...)
whenever they would be imported/use.
|
Yes this faking of dependencies is certainly possible and actually quite a common problem on RTD. They also kindly provide a solution to this in their FAQ |
Yes this faking of dependencies is certainly possible and actually
quite a common problem on RTD. They also kindly provide a solution to
this in their [1]FAQ
Right; I should have been more specific. What I am missing in the
MagicMock library is a recursive feature, because mocking all sage
modules sounds like a pain.
```
In [1]: import sys
...: from unittest.mock import MagicMock
In [2]: class Mock(MagicMock):
...: @classmethod
...: def __getattr__(cls, name):
...: return MagicMock()
In [3]: MOCK_MODULES = ['sage']
In [4]: sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
In [5]: import sage
In [7]: from sage import Blah
In [8]: class A(Blah):
...: pass
```
So far that's great. But I would like to further do:
```
In [6]: import sage.foo
---------------------------------------------------------------------------
ModuleNotFoundError Traceback (most recent call last)
<ipython-input-6-4ecbf9786377> in <module>()
----> 1 import sage.foo
ModuleNotFoundError: No module named 'sage.foo'
In [10]: from sage.foo import Blah
```
Well, maybe that's not so bad after all, and we could just have one
big list in sage_package that would get updated from time to time:
```
MOCK_MODULES = ['sage', 'sage.foo', 'sage.foo.bar', ...]
```
Cheers,
|
You are right that mocking all sage modules would be a huge pain. But a package would only need to mock the sage modules it is actually importing from. That being said, I tried what I could do by hooking the import mechanism of python. And it seems you can solve it this way:
As it shows, you can still import existing modules, and raises an error on non existing modules. But only the submodules of "a" are imported.
since there is no way to know at the point of the |
So we should encourage people to not use * imports, which is always a good idea. |
You are right that mocking all sage modules would be a huge pain. But a
package would only need to mock the sage modules it is actually
importing from. That being said, I tried what I could do by hooking the
import mechanism of python. And it seems you can solve it this way:
...
sys.meta_path=[MockImporter(["a"])]
import a.v.g.d.s.f
from a.hs.sdfhd.gs import *
from a.adgagds.gad.agd import l
Ah ah! That's exactly what I was dreaming of! Nicely done :-)
I am curious to see how this idea behaves in production. Putting
sage_sample on RTD would be a good first test. Do you have a chance?
Putting my sage-semigroups package on RTD would be a serious check
given all the recursive monkey patching tricks there. I am not sure
when I'll get to that any time soon though.
But like the original workaround on RTD it doesn't work if some code
is doing:
from a import *
some_function_imported_from_a()
Fair enough. As you say, I don't mind discouraging the use of * imports :-)
|
There's one minor issues with this, namely Sphinx won't generate documentation for classes that inherit from a MagicMock. I am not sure why exactly but something needs to be disabled on the mocks to make this fully work. |
To quote from my e-mail just now: RTD has changed a little bit lately. I haven't configured a new |
My point is, in principle, mocking might not be necessary at all if you can create docker image based on RTD's official images but that includes Sage. I don't know for sure yet how feasible that is. |
Ok. Let's move this discussion here rather than into these private emails ;) |
See MCLF/mclf#107 for an attempt to build with conda-forge on RTD. |
I did not manage to get this to work. Running |
https://readthedocs.org/ can be a nice way for sage packages to make their documentation available. So it would be nice to investigate how to showcase how to do this in sage_sample.
A first attempt is here: https://readthedocs.org/projects/sage-sample/
As expected, the difficulty is that compiling the documentation with Sphinx requires importing the Sage library. So we need to figure out a way to specify that Sage is a dependency (see readthedocs's build process). At this stage, we can't do it in setup.py.
There also are some ressource limitations; but as long as we do a binary install of Sage, that should not be a problem (unless they have also a disk space limitation).
cc: @embray
The text was updated successfully, but these errors were encountered: