[BBS-277] [Suggestion] Stop tracking auto-generated API docs

[Stannislav]

This is an example implementation for the corresponding JIRA ticket.

Consider this as a suggestion, it can be closed any time.

[jankrepl]

As pointed out elsewhere, I think it is a great idea and I am not sure why this is not the standard practice. Unfortunately, we would need to "hack" the ReadTheDocs to make it work on their servers. And since now it is clear that we are going to go for RTDs this PR might not be desirable.

Anyway, maybe there is a non-hacky solution so do not take my word for it.

[FrancescoCasalegno]

Hi @Stannislav ,

From what I read in the JIRA ticket, the only real downside of this PR is that it will make impossible or very tricky to upload the docs to RTD. @jankrepl can you confirm that I understood correctly?

If this is the case, I suggest this PR is closed since the open sourcing process does include removing the docs from the internal BBP docs hosting and push them to RTD instead.

[jankrepl]

Hi @Stannislav ,

From what I read in the JIRA ticket, the only real downside of this PR is that it will make impossible or very tricky to upload the docs to RTD. @jankrepl can you confirm that I understood correctly?

If this is the case, I suggest this PR is closed since the open sourcing process does include removing the docs from the internal BBP docs hosting and push them to RTD instead.

My reference is this readthedocs/readthedocs.org#1139. To me it seems like the only way is to call the sphinx-apidoc from a subprocess created within Python. I find that hacky. Note that without these directives, we can never have the API docs on RTD.

[Stannislav]

Hi @jankrepl @FrancescoCasalegno , yes I had in mind that we wouldn't host on RTD. But now that we will it's a problem like Honza pointed out. So let's close this PR and the JIRA ticket.

Stale apidoc rst-files might still be a thing, so we'll need to keep in mind re-generating them before pushing to RTD.