Documentation for tango attributes with readthedocs

[limonkufu]

Hi, I don't know if this is the place to ask this question but I am having trouble documenting tango attributes with autodoc on readthedocs.

I have autodoc_mock_imports = ['Pytango', 'tango', 'tango.server' ,...] but this just produces "Used by autodoc_mock_imports." for the attributes with default readthedocs build (sphinx version 1.8.5). Since I can't import tango I am not sure how to do this on the readthedocs server. (I am able to generate documentation for attributes on my local machine as I can import tango)

I tried upgrading the sphinx version to see what happens and the attribute fields are not showing at all. I tried mimicking how this repo does it (basically copying conf.py, mock_tango_extension.py) but since I can't import tango or its source files (I can't install the dependencies on the readthedocs server, and I can't import source files), it didn't work.

I know this is not really related to pytango but if anyone here could show me how I would be thankful.

[ajoubertza]

Maybe @reszelaz or @cpascual can comment? I see this PR, https://github.com/taurus-org/taurus/pull/724, where they moved away from RTD, mentioning the burden of maintaining mocks. Similar work done in Sardana.

[cpascual]

First, regarding the problem of mocking in RTD: we did that the beginning and managed to build reasonable docs, but it was too much effort and needed continuous maintainance. In short: I would not recommend doing it if you want to use autodoc (it is fine if you do not autodoc the classes, but if you autodoc something that inherits from a mocked class you need to do too much custom work on the mock itself).

But, for PyTango, all the dependencies are available in conda, and therefore in principle it should be easy to just use RTD's conda support to install all dependencies and not using mocks at all.

Still, since @ajoubertza mentioned it, I will comment on the more radical solution of moving away from readthedocs and switch to building the docs directly as part of the CI (in travis) and then deploying them to github pages. We are very happy with this for the following reasons:

• we build the docs as part of our test suite (i.e. we want builds to fail if the docs get broken). Then we are already generating the docs anyway
• we get rid of one 3rd party integration (less overhead managing the RTD account) and manage all the CI in one single place
• it is a lot more flexible than RTD (you can easily install all dependencies)
• you can use the same recipe for non-python packages.
• you do not get ads in your pages (although RTD allowed to suppress them, I think)

The only point against this is that RTD automatically generates and publishes pdf/epub versions of the docs, while you need to implement it manually if you need it in github pages.

Similarly, RTD makes it more automatic to serve "alternative" versions of the docs based on different branches. In Taurus we have this solved with a bit of custom javascript.

The transition from RTD to github pages is very easy since you can implement the github-pages deployment in parallel while still using RTD. Then, only once you are happy with the results you can change the DNS settings to point your domain to the github pages version.

Note 1: regarding technical details on how to deploy to github pages, Taurus is using doctr, as seen here. But IMHO the implementation in sardana is simpler, more straitght-forward and more portable.

Note 2: even if PyTango will probably not use it, I want to mention that if your project is hosted in gitlab instead of github, the gitlab-ci+gitlab pages is even more convenient for this than github/travis+github pages

[limonkufu]

Thanks for your help @ajoubertza @cpascual very much.

I will try the conda environment for now and I was already generating gitlab pages as part of my pipeline(since it was easy to do :)) but didn't change the DNS settings to point it to my domain. I will experiment with it.

[limonkufu]

Just to let you know, using conda env seems to work with attributes without mocking. I followed https://taurus-scada.org/users/getting_started.html#installing-in-a-conda-environment-platform-independent this to install pytango to my project.

[ajoubertza]

@Limonkufu That's good news. I'm closing this as it sounds like your issue has been resolved.