Config: Reuse docs/user/config-file/examples in django templates

[benjaoming]

In #10301, we are starting to reuse configuration examples across different documentation files. We are also storing them in a way that they can potentially be built by Read the Docs using custom configuration file paths.

Once #10301 is merged, let's try to symlink these files into the django templates and see if we can ensure maximum consistency across all configuration file examples.

We need to ensure that the approach works for readthedocs-corporate as well (we might have to swap symlink source and target so the actual files get to exist in the Python package instead of the docs).

[humitos]

We are also storing them in a way that they can potentially be built by Read the Docs using custom configuration file paths.

I would avoid making these examples run-able from the main repository. If we want to test these examples, we should create test-build branches that use them.

Once #10301 is merged, let's try to symlink these files into the django templates and see if we can ensure maximum consistency across all configuration file examples.

I'd also avoid symlinks -- we had pretty bad experiences in the past that I don't want to remember 🥲

That said, I think the best pattern we can follow here is just storing each different use-case in a YAML file and use .. include:: from the documentation and {% include %} from the Django templates. That seems easier to do and follow standard patterns we have been following already.

[benjaoming]

@humitos With regard to building example configuration files, what I'd like to see is a continuous verification of example configuration files:

1. If someone changes the example, is it still valid or does it contain a typo?
2. Do we make other changes on the platform and forget to update our examples so they break?
3. Once we start adding very detailed examples in our docs (for instance for specific documentation tools), how can we ensure that the example works?

But I think that there is one very very important structural change that out-does all of the above: If we start to maintain all our user-facing examples in docs/config-file/examples, then we've already gone 80% of the way :)

I'm not saying that the end-goal here is to over-load the main repo with the same kind of setups that test-builds is for. But I think that it can be a good idea to have a more structured approach and leverage that for better test integration. There's a separate issue on cleaning up test-builds. So hopefully this initiative can also give some new inspiration.

Edit: An example of the above would be to simply check that the YAML code validates with our config parser.

I'd also avoid symlinks -- we had pretty bad experiences in the past that I don't want to remember smiling_face_with_tear

Ah yeah, it's not my personal go-to solution for such cases, but I saw symlinks being used in ext-theme templates and for files in common/... sliding down that slipper slope :)

That said, I think the best pattern we can follow here is just storing each different use-case in a YAML file and use .. include:: from the documentation and {% include %} from the Django templates.

I think we should try to make it work without symlinks for sure, and you might be right that .. include can read files outside of the Sphinx project folder, so let's see 👍

[humitos]

I'm closing this issue for now since we weren't able to prioritize and it fell off from our roadmap already. We can come back to it in the future if we hit this problem again.