Reconsider tag name scheme for RTD

[dhermes]

Using umbrella-0.20.0 did not kick off a stable docs build on RTD. From their documentation, a stable build is only done when a semver-valid tag is pushed:

You should push a tag for each version of your project. These tags should be numbered in a way that is consistent with semantic versioning. This will map to your stable branch by default.

I tried to force it to rebuild but it stuck with the last valid tag at 4d66524.

[dhermes]

To add more context, the link I gave above actual says they expect the tag to be PEP 440 compliant. We can check for said compliance via the packaging package.

Essentially the only extra pieces outside of x.y.z allowed are: dev version (integer), epoch value (should not use), local / build metadata (anything we want), post and pre release (must be integer).

So the only real place to sneak in the package name is in the local part.

---

To see some valid and invalid (according to PEP 440) version (hence tag) names:

>>> import json
>>> from packaging.version import Version
>>> v = Version('0.20.1')
>>> print(json.dumps(v._version.__dict__, indent=2, sort_keys=True))
{
  "dev": null,
  "epoch": 0,
  "local": null,
  "post": null,
  "pre": null,
  "release": [
    0,
    20,
    1
  ]
}
>>> v = Version('0.20.1+datastore')
>>> print(json.dumps(v._version.__dict__, indent=2, sort_keys=True))
{
  "dev": null,
  "epoch": 0,
  "local": [
    "datastore"
  ],
  "post": null,
  "pre": null,
  "release": [
    0,
    20,
    1
  ]
}
>>> Version('0.20.1-datastore')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/dhermes/Desktop/venv/local/lib/python2.7/site-packages/packaging/version.py", line 202, in __init__
    raise InvalidVersion("Invalid version: '{0}'".format(version))
packaging.version.InvalidVersion: Invalid version: '0.20.1-datastore'

[daspecster]

What about 0.20.1+1234, where 1234 is essentially a build number?

[dhermes]

Yeah that's also valid. But the reason for tags is to do releases of each subpackage with a tag. Check out https://github.com/GoogleCloudPlatform/google-cloud-node/releases to see what I'm talking about.

Hence we want a PEP 440 valid tag (so RTD is happy) but we also want to put info in the tag that tells us which version to release.

[dhermes]

Per @tseaver, we'd like the tags to start with datastore-* etc., but that may be a non-starter for making RTD happy.

[daspecster]

So this might be the wrong question but what if the subpackages had their own docs and the umbrella package just linked to the other subpackages docs?

Then versions/tags can be treated normally for each subpackage right?

[dhermes]

Then versions/tags can be treated normally for each subpackage right

That would mean entirely different source trees / GitHub projects, which has been disallowed?

[tseaver]

What if the subpackages had their own docs and the umbrella package just linked to the other subpackages docs?

@daspecster That would be ideal in a sense, but it would almost require separate repositories for each API.

[daspecster]

Looks like it might be possible? readthedocs/readthedocs.org#1554

[dhermes]

I'm somewhat 👎 on this as well. Essentially, the same reason we want a single place for filing issues, we want a single place for documentation (I realize the inherent contradiction since we have gh-pages and RTD docs).

[tseaver]

ISTM that having separate RTD projects for each API might be the Right Thing(TM): each PyPI page would point there, for instance. The "master" docs would then include only the overview stuff, with intersphinx links to the separate projects.

[dhermes]

I think I'd be OK with that. I don't think that gets us around the stable / PEP 420 issue.