Version Picker Issues on Dev Manual

[Bibo-Joshi]

Hi there,

I've noticed some confusing behavior of the version picker in the lower left corner of the dev manual.

• clicking on any link to the dev maunal on https://docs.nextcloud.com/ will open the desired version, but the version picker in the lower left corner will always say "latest" independent of the actual version. the only way to check which version you're currently reading is checking the URL. This is my main source of confusion
• In the version picker, only the last few versions are available, never the complete history back to version 12. This may not be critical, but it's still surprising IMO.
• the stable version is available only as stable in the version picker, not through the explicit version number. At the time of writing the issue that means: In the version picker, I see latest, stable, 31, 30, 29, but not 32. Replacing stable with 32 in the url does work, however. This, too, might not be too bad at first glance, but makes permalinking harder and IMO can also make it less transparent what stable refers to

What I already saw is that you build the dev manual with sphinx, but didn't quite understand the configuration and how the hosting is done. In this workflow builds are run, but uploads only go to artifact-storage, no actual deployment IISC. In the sphinx config, I found

documentation/developer_manual/conf.py

Lines 66 to 70 in 96a9c54

	# Add canonical link in all generated pages linking to their respective equivalent
	# in `stable` (regardless of which version of the docs someone lands in).
	# Note, there is an argument to be made for having this link to `latest` instead,
	# but this is likely good enough and the most conservative for now.
	html_baseurl = "https://docs.nextcloud.com/server/stable/developer_manual/"

which looks a bit surprising to me. The available versions apparently are defined at

documentation/conf.py

Lines 50 to 65 in 96a9c54

	# building the versions list
	version_start = 29 # THIS IS THE OLDEST SUPPORTED VERSION NUMBER
	# THIS IS THE VERSION THAT IS MAPPED TO https://docs.nextcloud.com/server/stable/
	version_stable = 31 # CHANGING IT MUST RESULT IN A CHANGE OF THE SYMLINK ON THE LIVE SERVER
	# Also search for "TODO ON RELEASE" in the rst files
	def generateVersionsDocs(current_docs):
	versions_doc = []
	for v in range(version_start, version_stable + 1):
	url = 'https://docs.nextcloud.com/server/%s/%s' % (str(v), current_docs)
	versions_doc.append(tuple((v, url)))
	versions_doc.append(tuple(('stable', 'https://docs.nextcloud.com/server/%s/%s' % ('stable', current_docs))))
	versions_doc.append(tuple(('latest', 'https://docs.nextcloud.com/server/%s/%s' % ('latest', current_docs))))
	return versions_doc

so my points 2 & 3 would likely be relatively easy to address. If you agree with my suggestions, then I'd be happy to send a PR for that.
I couldn't find anything about point 1 though. If you have pointers on what'd need to be addressed, I'd also be happy to PR.

Looking forward to your reply.

Best
Hinrich

PS: I chose the "blank issue" rather than the "Documentation Improvement" issue template as this is more of a meta/configuration-bug, not about the actual content. If you prefer to have the issue in the template, I'm happy to re-create.

[joshtrichards]

I agree—these issues annoy me too! And they impact all the manuals (dev, admin, user) essentially similarly. 😂

I think your suspicions are “in the ballpark” (though I might be wrong as well!).

There are likely various possible solutions.

When I've looked a bit, the challenges tend to pop up in three areas:

• URL building/mapping

• Cross-branch matters¹

  • Builds and deploys for different manual versions happen from within the context of the relevant branch (or version).
  • i.e. configuration differences, like static version ranges/mapping embedded in conf.py.

• Static docs

  • The distributed HTML docs (effectively static artifacts, either embedded within Nextcloud or distributed separately) may have a different perspective on what is “latest,” compared to the live website.
  • Same goes for PDF documentation.

(I'm personally less concerned about this last one.)

P.S. These matters overall are (presumably) mingled in with a roadblock I recently encountered while trying to automatically have the end-of-support banner appear on older branches as they age out.

---

Footnotes

1. The way docs for different release trees are managed and built interacts with conf.py's perspective in each build context. For example, the master branch always represents whatever is truly latest. Builds from that branch are considered “latest” (at build time). In contrast, the stable32 branch represents the most recent iteration of the v32 manual—but at build time, the context doesn’t inherently “know” that it’s not the latest for v32. :) ↩