Replace current import process for Github with Actions integration

[wvxvw]

Current process of uploading the documentation is extremely uncomfortable, to the point that it is impossible to make it work.

I have multiple problems with how your script is trying to invoke Sphinx, how it is trying to install Python packages, and how it is unable to use existing artifacts created by other actions, unable to use the environment created through actions.

To make this more concrete: my project uses tesseract-ocr library, which will only install successfully if the relevant headers are found on the system trying to install it. It's easy to do this in Github Actions, but impossible using the integration that exists today between ReadTheDocs and Github. Furthermore, to generate the documentation, I need to invoke apidoc command before I run anything else related to Sphinx. There's an ugly workaround for this: one can add the code to run documentation generation to the Sphinx configuration file... which is terrible on multiple counts I don't want to go into, but most importantly, the way you load configuration file and the way it's normally loaded by CI is different, and it causes various problems related to locating files that need to be documented.

Furthermore, you are using pip to install packages. It's terrible. I don't want that. But, it seems I've no option to use setup.py to do that, even though that's the only way that actually works!

Obviously, not being able to reuse the code written for other Github integration is upsetting, but I would get over it if there was at least some way to integrate with ReadTheDocs.

[stsewd]

Hi, I think #1083 is what you are referring to.

[wvxvw]

Yes, this looks close. So, there's no way to upload existing documentation? Bah... I'd expect this to be the first thing one would implement when it comes to such a service... guess I thought wrong.

So, correct me if I'm wrong, since I need headers that aren't in Docker image used by ReadTheDocs to build documentation, there is no way I could upload it to their service, not even if I'm willing to put effort into fiddling with configuration etc?

[stsewd]

Yes, this looks close. So, there's no way to upload existing documentation? Bah... I'd expect this to be the first thing one would implement when it comes to such a service... guess I thought wrong.

There are a lot of things that we do that require us to have some control over the build in order to be able to provide our features. Like inject our version selector, index the content of pages to be able to use our server side search, we are trying to do those in a more generic way, but for now that's required, so we can't just upload html.

https://tesseract-ocr.github.io/tessdoc/Compiling.html#linux looks like there is an ubuntu package, you may be able to install it in the future #8065. You can also try using conda, maybe the package is there. But do you really need to install that library to build your docs? You can try mocking it https://docs.readthedocs.io/en/stable/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules

[astrojuanlu]

Hi @wvxvw - apart from what @stsewd said (that we're working to make the build process more flexible), I notice in https://github.com/drcandacemakedamoore/cleanX#documentation that you're using setup.py to add additional commands. Just FYI, current Python packaging practices discourage this, since setuptools now recommends static configuration with setup.cfg and the safest way to install packages is using pip install. I'm not sure what you mean by "installing with pip is terrible", but hope this clarifies things.

[astrojuanlu]

And finally, after investigating this a bit, I think for apidoc in particular this extension does exactly what you need https://github.com/sphinx-contrib/apidoc without having to add a custom command. Please let us know if it works.

Related: #7162

[wvxvw]

current Python packaging practices discourage this, since setuptools now recommends static configuration with setup.cfg

Python community is in such a state that if you hear that you do something that's discouraged by it, you may be certain you are doing it right. Yes, setup.py is the way to go, it's how it should be done. setup.py isn't great, but all other options out there are a lot worse.

I believe that the reasons these random thoughts pop up around the Internet is that at one point there was very little activity in setuptools department (understandably, it's a terrible mess of a code), and pip, for ages, was promising to come up with something better. Something better never happened, and setuptools is still the only way it's possible to make things work (mind it, it's still terrible, but at least, for any given task, with a lot of massaging, you will be able to beat things into the shape you want).

As for extensions: thank you, but no. I don't want to deal with extensions. This task doesn't warrant an extension, and it should have never worked the way it does now. It should've worked the way JavaDocs or Doxigen or dozens of similar tools out there work: the developer puts annotations on their code, the documentation tool collects them and produces documentation. The documentation tool that needs an extension to... generate documentation is... well, something that would definitely exist in Python world, but would come as a huge surprise to anyone unfamiliar with the way Python is.

Anyways, it's pointless to tell you this, as none of this is going to change, and I should really not care this much about it.

Have a good day.