Version-specific documentation proposal

  • ← version selector
  • ← no version selector

I was confused by why that is, since the index.html in the two directories are essentially identical.

Looking at the version_redirect.json, I found it to be missing recent changes, including the version picker. But also all other files were somehow built from an older commit with many recent additions missing. I guess the TeamCity build wasn’t a good source. For the time being I can take care of it manually on my machine until we have some standard environment and automation in place.

Fixed in Should be picked up for deployment on the next syncthing/docs commit. Which could be merging some variant of, that would have helped spot the error earlier?

Probably I messed up something wrangling it. Thanks for sorting it out. Let’s try to sort out some sort of automation to prevent it in the future. It’s obviously not ideal to different build processes for the stuff to be included in pre-rendered and the thing that is live on the web, either…

Definitely. But going back to an even older Sphinx version by using the Netlify / TeamCity / Docker builds would be unfortunate. Let’s see which of them we can get at least up-to-date with the latest builds in docs-pre-rendered.

Both Netlify (by default) and our build (after tweaking) could properly use requirements.txt etc to pip in the correct sphinx stuff, I think.

That’s true for Sphinx and docutils. Dunno if Ubuntu base version and its included Python makes any difference, but Latexmk is not imported by pip IIUC.

Just to be clear: I think this is what should happen automation-wise: (made with, if you want to adjust it I can provide the code)

Dashed arrows show what is not yet implemented.

Yeah I have a Docker image for that stuff for that reason, though now with a somewhat outdated sphinx etc.

Preferably we would build the docs once, with a stable environment, and then push that to live and the pre-rendered stuff (on tags). Not sure that’s supported with Netlify. There are obviously other services that can serve it in that case, maybe even GitHub pages (though that may require pushing the completed build to a separate repo for publishing…).

I’m trying to get that image up and running to test and propose adjustments. But my Docker skills are severely limited, so I can’t get it to resolve DNS entries despite passing docker build --network=host. How is that to be used?

EDIT: I could at least verify what versions it will use. Looks like Python 3.9 and latexmk 4.70b, which is newer than my versions, so good. Increasing the pip requirements should fix the Docker build then.

How can we allow using the same procedure as in within the Docker environment? does something different. Sorry for all these noob questions, I’m not experienced with containers and distributed build automation at all.

Also tying the versions in requirements.txt to what is used in the Docker build seems sensible. I don’t see how currently makes sure of that.