I'm struggling a bit with uploading docs for my projects. I see that devpi has support for distutils-based docs uploads, and I commend you for the work creating a PyPI-compatible interface for docs.
It might be fairly straightforward to simply continue to support the
upload_docs command for devpi usage, but it has several irreconcilable differences with the way RTD builds docs:
- RTD always builds from the
setup.pyis invoked from the project root. As a result, any references to files in the project dir can't support both environments without careful resolution of the cwd.
setup_requiresdependencies which are often a poor approximation of the dependencies needed for building docs. There's no standard way to declare the dependencies needed for building docs. RTD has a nice model for this - one can specify a requirements.txt and can opt to install the project (a little redundant, actually).
- RTD implies that Sphinx is installed; build_sphinx requires it to be installed.
There are other issues as well, like authentication and specification of the pypi repository, which I believe has to be supplied redundantly with the
upload command. I'm not sure if the password will be resolved from the keyring or from devpi. Does
devpi upload --with-docs pass devpi credentials to the upload_docs command?
What I'd rather see is native support for uploading docs (built by some other process) and maybe consider if a devpi build-docs command might replicate the RTD model, which while opinionated does form something of a basis for a standard.