feat(docs): fetch docs from monorepository branches

[innocenzi]

This pull request updates how the versioning of docs works.

Instead of having a content directory with all copies of all versions, we have a docs:pull command that fetches documentation from tempestphp/tempest-framework:docs. The docs directory of the monorepository should contain all the documentation.

During local development, we can do tempest docs:pull or tempest docs:pull 1.x for a specific version. During deployment, we need to do tempest docs:pull as well before static page generation.

This is mainly for improving the experience or editing docs when we support multiple versions, because it's easy to edit a file for a different version by mistake. To go ahead with this, we need to first migrate the current docs to a docs directory on the main and 2.x branches

This PR also updates the docs URLs to be immutable. We had this conversation already, but here is a summary:

• We have immutable URLs by default (eg. /docs redirects to the current version, right now it's /1.x)
• Outdated URLs get a noindex meta and a canonical URL to the current version (eg. if the current version is 2.x, a /1.x/foo/bar URL would get a canonical to /2.x/foo/bar)
• This ensures saved docs page don't 404 in the future
• This ensures search engines don't keep outdated docs in search results
• For better UX you should use immutable URLs in your blog posts, not /docs one

[brendt]

Couple of questions:

• Can we make it so that pushes on the docs repo's main branch also trigger a (simplified) deployment?
• I'm worried about local dev having to always run docs:pull. When I'm writing docs, I like to see the changes in the browser. If possible I like to see those changes in real time.
• Do I understand correctly that the docs then always live in the docs branch in tempest/framework? Or did you mean the docs/ directory? I haven't read through the code yet, but this confused me a bit. My assumption would be that a docs/ directory makes most sense, because then we version it together with the framework. I think that's the case, but you mentioning tempestphp/tempest-framework:docs confused me (because that's the notation for a branch)

[innocenzi]

Can we make it so that pushes on the docs repo's main branch also trigger a (simplified) deployment?

Not sure how yet, but should be feasible yeah!

I'm worried about local dev having to always run docs:pull.

That's one step added but I think it's beneficial in the long run. We could add that to a post update hook too

When I'm writing docs, I like to see the changes in the browser. If possible I like to see those changes in real time.

Yeah good point actually... besides using the usual workflow after a pull and copy-pasting back to the main repo, I don't see a good solution here

Do I understand correctly that the docs then always live in the docs branch

I explained it bad: it's in each version's branch inside a docs subdirectory. My notation is wrong as well

[brendt]

Yeah good point actually... besides using the usual workflow after a pull and copy-pasting back to the main repo, I don't see a good solution here

Could we make it so that we symlink the docs folder locally? Maybe even with a command. Something like docs:symlink? Possible by passing in a path (but assuming the default path is ../tempest-framework)

I explained it bad: it's in each version's branch inside a docs subdirectory. My notation is wrong as well

I figured, but wanted to be sure. Perfect

[innocenzi]

That's a really good idea. I implemented that, let me know!