This article assumes that you are working with the TYPO3 recommended way, using the TYPO3 Example Restructured Text Documentation.
Settings.cfg is not for your variables
In the Settings.cfg you can define variables for docs.typo3.org to add additional information to your documentation.
Use substitutions
With substitutions, you can replace placeholders with custom values. This helps you keep your information in sync across your documentation.
The TYPO3 example documentation comes with an includes.txt included. Every file in the example documentation includes this file by default.
To define your substitution, add the following line to your includes.txt:
.. |extkey| replace:: statictagcloud
Help your users with extension upgrades
Not documenting breaking changes will not only make your life harder down the road but also the lives of your users. Updating extensions trough multiple versions can be a real headache if a lot has changed. Keeping track of what changed will help to identify what needs manual changes to make the extension work.
Sitemap not updating
Changing the structure of your documentation it is possible that it will not update the sitemap. You can solve this by deleting the cache directory in the generated documentation folder.
Using a file-watcher
Instead of manually re-rendering the documentation, you can let a file watcher do this for you. Here an example using the onchange npm package and docker-compose.
Install the onchange package globally:
npm install onchange -g
Run the following command in your extension folder:
onchange Documentation -- docker run --rm -v $PWD:/PROJECT:ro -v $PWD/Documentation-GENERATED-temp:/RESULT t3docs/render-documentation makehtml