search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
7.99k stars 3.58k forks source link

APIv3: download `htmlzip` files #8155

Open tareshsethi opened 3 years ago

tareshsethi commented 3 years ago

Is there a way to programmatically download an htmlzip of a version, say given the personal access token (apiv3)? Hoping to do something like this in python ...

HEADERS = {'Authorization': f'token {read_the_docs_token}'}
r = requests.get(zipurl, headers=HEADERS, stream=True)

Thanks!

stsewd commented 3 years ago

@tareshsethi hi, do you mean when using private projects in readthedocs.com? If you are using readthedocs.org everything is public, so you can download files without a token.

tareshsethi commented 3 years ago

@stsewd thanks! Yes, for private projects on readthedocs.com.

More generally, I was hoping to create an oauth 2.0 client for private projects in readthedocs.com so that I could programmatically download the html zip on every build on behalf of a user (for example: gdrive has https://developers.google.com/identity/protocols/oauth2 and confluence has https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/). It seems like there's no way of doing so yet for readthedocs.com with apiv3. If I could download with a personal access token, that would suffice for now. Let me know if there's any way to authenticate as a user and download the htmlzip

tareshsethi commented 3 years ago

Quick follow up question to that - will every project (both public on readthedocs.org and private on readthedocs.com) have downloadable html zips? Can a company or host choose to disable the download feature? If so, would there be a way to access the htmlzip in some other way?

stsewd commented 3 years ago

@tareshsethi htmlzips are optional, they aren't included by default when using a v2 config file https://docs.readthedocs.io/en/stable/config-file/v2.html#formats. You can check if a project has a zip file with the API v3 https://docs.readthedocs.io/en/stable/api/v3.html#version-detail (downloads).

Since downloads are served from the same domain as docs, you can use a sharing token https://docs.readthedocs.io/en/stable/commercial/sharing.html#http-authorization-header. A sharing token is a per-project token, so a user would need to create one for each project.

But yeah, I think would be useful to have this feature under API v3.

tareshsethi commented 3 years ago

that helps a ton - thanks so much!