Add a warning that docs are WIP and a status flag for articles

[YuriSizov]

Depends on #6814.

This PR adds a togglable warning about docs being WIP, advising to pay attention to itself to learn if the page is up to date or not. By default every page is considered outdated. To mark it as up to date, we must add a flag to its metadata (a field at the top of the document), like

:article_updated: True

See index.rst for an example.

---

Now, obviously, this is a lot of busywork to verify every article, but I think it's better to default to being outdated than to default to being up to date, because that's closer to the true state of the docs. Many articles still need an update pass, even though others have been updated or even rewritten. The outdated banner also has a call to action, so this should hopefully incentivize people to contribute or to at least validate the actuality of the docs.

If we don't agree on this, I can remake the defaults or implement the logic differently.

---

Here's how it looks (I made some adjustments to the admonition banners in general):

[YuriSizov]

After we agree on this, make_rst in the main repo needs to be updated, because the class reference should all be marked as up to date.

[and-rad]

First thing that comes to mind is how is this going to play out in the future? The engine keeps changing, documentation that is now up to date will become out of date again. Would there be some kind of hook that sets :article_updated: to false every time a major engine version is being released? Will people have to do it manually?

[YuriSizov]

We don't have to look so far ahead. This is only needed right now to address the issue with massive changes in 4.0. We can reuse this or scrap it afterwards, we will see.

Eithet way, it will involve manual labor.

[clayjohn]

I would prefer if every page defaulted to up-to-date. Otherwise we need to ask contributors to review every single article and flag it as updated.

By defaulting to up-to-date, we will quickly find out from users which pages are out of date and we can easily add the warning to just those pages

[YuriSizov]

Otherwise we need to ask contributors to review every single article and flag it as updated.

I'll do broad strokes myself, and I'll make a tracker for all the areas so we can split the load.

I'd prefer the default state to be cautious. Otherwise the point of this warning to most users is nil, until someone complains (while others stay silent and perhaps confused)

[clayjohn]

Otherwise we need to ask contributors to review every single article and flag it as updated.

I'll do broad strokes myself, and I'll make a tracker for all the areas so we can split the load.

I'd prefer the default state to be cautious. Otherwise the point of this warning to most users is nil, until someone complains (while others stay silent and perhaps confused)

On the other hand, if we release 4.0 and every article says its out of date, users are going to be very confused and upset.

I wonder if there is a way through git to flag all the files that have been touched between two commits. Maybe we could flag only those files that haven't been touched at all in the last couple of years

[YuriSizov]

I wonder if there is a way through git to flag all the files that have been touched between two commits. Maybe we could flag only those files that haven't been touched at all in the last couple of years

That is basically what I'll do tomorrow, but manually 🙃

[YuriSizov]

After thinking about it and since I plan to do a manual pass today, defaulting to up to date should be okay and benefits in the following ways:

• The flag is only needed in outdated articles, removing it makes the final state of the docs cleaner, because after we are done we won't need to go over again and remove the flags from everywhere;
• Currently open PRs don't need to be updated to add a flag if they update or create a page (though they might need to remove it).

[YuriSizov]

Tracker for outdated docs

I'll mark the sections as I go through them.

About

• Introduction
• FAQ
• Troubleshooting
• List of features
• Documentation changelog
• Godot release policy
• Complying with licenses

Getting started

• Introduction
• Step by step
• Your first 2D game
• Your first 3D game

Manual

• Best practices
• Editor introduction
• Migrating to a new version
• 2D
• 3D
• Animation
• Assets pipeline
• Audio
• Export
• Internationalization
• Inputs
• Input and Output (I/O)
• Math
• Navigation
• Networking
• Performance
• Physics
• Platform-specific
• Plugins
• Rendering
• Scripting
• Shaders
• User interface
• XR

Contributing

• Ways to contribute
• Contribution workflow
• Engine development
• Writing documentation

Community

• Consider all pages to be up-to-date
• Some changes may still be in order to differentiate between 3.x and 4.x resources

Class reference

• Consider all pages to be up-to-date

[Sauermann]

2D/Canvas layers: looking correct
2D/Viewport and canvas transforms: missing descriptions about several details (see rewrite of this article in #6277)
Inputs/Using InputEvent: mostly correct, missing infos about a few changes
Inputs/Input examples: only had a quick look and looks good in broad strokes. some details are missing
Inputs/Mouse and input coordinates: looking good
Inputs/Handling quit requests: looking good

[YuriSizov]

Okay, I'm done. Any article marked with article_outdated is a good candidate for proofreading and a PR. Some already have a PR too. As those articles are updated, the banner should be removed.

Edit: Slightly changed the text in the warning message too, by the way.