search

readthedocs / readthedocs.org

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

API V3: document how slugs are generated #6746

Open KengoTODA opened 4 years ago

KengoTODA commented 4 years ago

Thanks for hacking such a useful product! 👏

Especially the public API is awesome for who's motivated to automate workflow. With help from your public API v3, I successfully replaced puppeteer that makes my bot really fat and unstable.

Here I have a request for future development (API v4?), I hope it helps your hack and your community.

In my understanding, I need to replace / in the name of branch with -, so I have code for it. However I found that this escape rule isn't documented in the API page. I also found no page describe about any escape rule.

I want to confirm that my understanding is OK, or know any missing rules that I need to consider.

KengoTODA commented 4 years ago

Ah, I probably need to say sanitize instead of escape...

stsewd commented 4 years ago

@KengoTODA you don't pass the branch/tag name to the api, but its slug. The slug is generated by rtd when the branch/tag is created. Currently, we don't offer a way of querying the version based on the original name.

Probably we should put on the docs that version-slug isn't the same as the branch/tag name

https://docs.readthedocs.io/en/stable/api/v3.html#versions

humitos commented 4 years ago

Probably we should put on the docs that version-slug isn't the same as the branch/tag name

This makes sense. There is no place where we communicate how we do the sanitize from names to slugs.

KengoTODA commented 4 years ago

Probably we should put on the docs that version-slug isn't the same as the branch/tag name

Cool, thanks.
I wish I'll have an official document about the spec "how to convert names to slags", then I can implement a RtdSlug class to represent it.

stale[bot] commented 4 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

KengoTODA commented 4 years ago

I think this issue is still not ready to close.