Manage redirects in the ReadTheDocs admin, programmatically
Project description
Manage redirects in the ReadTheDocs admin, programmatically. Addressing the rtfd/readthedocs.org#2904 issue.
Installation
Requires Python 3.6 and higher.
$ pip install rtd-redirects
Usage
$ rtd-redirects project-name ./redirects.yml --username=honzajavorek
Uploads redirects defined in the redirects.yml file to ReadTheDocs redirects administration of the project-name project.
The tool uses ReadTheDocs’ HTML interface (there’s no official API for redirects), so you need to provide your username and password. HTTPS is used to transfer the credentials to ReadTheDocs.
rtd-redirects tries to be idempotent, i.e. you can run it several times in row and it should always end with the same results. If there are any redirects with the same source path, the tool will replace them with whatever is defined in the redirects.yml file. Existing redirects which do not collide with contents of redirects.yml won’t be affected.
redirects.yml
Only page redirects are supported at the moment. The format of the file is as follows:
redirects:
# we've migrated from MkDocs to Sphinx
"/example/": "/example.html"
"/python/": "/python.html"
# page removed in favor of section
"/green.html": "/colors.html#green"
# only for convenience
"/praha.html": "/prague.html"
Why YAML? Because it’s easy to read by humans, easy to write by humans, and above all, it has support for comments. Redirects are corrections and you should document why they’re necessary.
Usage with ReadTheDocs PRO
If you are using a commercial edition of the RTD (from readthedocs.com instead of readthedocs.org), please specify --pro flag in the command, like this
$ rtd-redirects project-name ./redirects.yml --username=honzajavorek --pro
There is also an opposite flag --free which is added by default, so can be omitted
License: MIT
© 2017-? Honza Javorek mail@honzajavorek.cz
This work is licensed under MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for rtd_redirects-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5b6a955bbbb12ae565a752ddef0ae068bf8d5c32affde844020523300ecaa8c3 |
|
MD5 | 70c48c8b4ecb1112b1d9c2e0e9c69746 |
|
BLAKE2b-256 | 077e8b8c36c38c21fc5a32290ec578edfe9d272b296d91932f9a5738295cc694 |