Add SWIG to containers

[jhale]

Would it be possible to add SWIG into the containers?

A little background: I work on a NumFOCUS project (fenicsproject.org) with a complex documentation chain that begins with Doxygen being run against our C++ library. We then convert Doxygen's XML output into a SWIG-compatible docstring.i file. So far so good and this all works very nicely on rtd.org. Thanks!

The issue comes because we need to use SWIG to generate the Python wrappers which includes the information from docstring.i. I understand how to mock out objects, so I know that I don't need to actually compile my SWIG-generated code to import it and have Sphinx do its magic. But I do need to re-run SWIG every commit to generate the wrappers that could have new docstrings extracted from the C++ code.

I hope I've managed to explain why I think SWIG would be useful in the RTD containers.

If this is acceptable, I will prepare the pull request.

See also:

readthedocs/readthedocs.org#2094

[agjohnson]

This sounds like it would be a good addition, but do you have an example of what this implementation might look like from the perspective of a user? I'm curious how you plan to use swig during the build process.

[jleni]

Hi @agjohnson
We need to use both cmake and swig3.0 to install our cryptography library

https://github.com/theQRL/qrllib

Unfortunately, PR #15 would not be enough (it is installing an older version), we need swig3.0.

You can find here how we use cmake to build and cmake in turn will detect C/C++ dependencies such as swig.

[jleni]

I can open an updated PR if you think it makes sense to merge it. Adding this missing dependency would be very useful for our project.

[agjohnson]

I'm curious what the actual implementation looks like for a Sphinx project on RTD. I don't see a Sphinx conf.py in your repository, so can't get an idea of how this would be called during a sphinx build.

[jleni]

It is a little more complicated in our case. qrllib (https://github.com/theQRL/qrllib) is deployed as a pip package what requires cmake/swig to get installed.

The main project ( https://github.com/theQRL/QRL ) is using Sphinx (one key dependency is qrllib).

When building the documentation for QRL. If I enable requirements.txt in advanced settings, build fails. On the other hand, if I dont get the requirements, the sphinx cannot pass some import statements and my documentation looks incomplete.

You can probably access my build logs here: https://readthedocs.org/dashboard/qrltest

[agjohnson]

Our general advice here is to mock out what dependencies are not directly required, but if you are trying to documet qrllib through autodoc, this of course doesn't work well.

If swig is just needed to run the pip install, this seems like it would be fine then. If system level swig is not enough, it should be fine to install from a third party source, as long as its a stable, maintained package.

[jleni]

No, we are not trying to document qrllib. I will then try mocking first.
Maybe that is enough and results in faster building time.
Thanks!

[humitos]

@jleni hi! were you able to try mocking this? did it work?

Please, can you update us here and let us know if the issue can be closed or it's still relevant. Thanks!

[jleni]

@humitos Hi!
I will send you an update tomorrow.

[humitos]

@jleni I'm reading your comment today. So, tomorrow is still fine for me :)

[hsorby]

I would like to have SWIG present in the Docker images so that I can have the Python API documentation for one of my C++ based projects on readthedocs.

[humitos]

hi @hsorby ! would you like to propose a PR, creating the docker image in your computer and checking that the version installed is enough for you and building your docs from there so we are sure that including swig dependency in our build image will work for your use case? Thanks!

Now, we have an option in our YAML that allows users to set the docker image to be used. After the PR gets merged and deployed to the servers we can start testing it live.

[humitos]

Hi all! swig was installed in our latest testing image 5.0rc1 (not released yet). I'd like to know if you want to help us testing it. In that case, please let me know what are the projects you are interested on testing it and I will apply this Docker image for its building process.

[hsorby]

I would like to try this Docker image for the libcellml project please.

[stsewd]

@hsorby 5.0 is the current image

[hsorby]

Oh sweet.

[hsorby]

Should I have been able to determine this for myself, I had a look but couldn't find evidence of which image was currently being used.

[stsewd]

You can check that here https://docs.readthedocs.io/en/stable/builds.html