mkdocs: READTHEDOCS environment variables are null on mkdocs.yml

Details

• Read the Docs project URL: https://readthedocs.org/projects/openvidu/
• Build URL (if applicable): https://readthedocs.org/projects/openvidu/builds/14834239/
• Read the Docs username (if applicable):

Our project is using:

• MkDocs 1.2.2

• Extra Context option in mkdocs.yml, with the ENV syntax to read environment variables, making the READTHEDOCS vars available to the template context:

  extra:
    READTHEDOCS: !ENV [READTHEDOCS, "(no var)"]
    READTHEDOCS_VERSION: !ENV [READTHEDOCS_VERSION, "(no var)"]
    READTHEDOCS_PROJECT: !ENV [READTHEDOCS_PROJECT, "(no var)"]
  

• Attempting to read the RtD environment variables as explained in Build environment and How do I change behavior when building with Read the Docs?.

Expected Result

1. The cat mkdocs.yml build step should show proper values for env vars READTHEDOCS, READTHEDOCS_VERSION, and READTHEDOCS_PROJECT.

2. A test html file with these contents:

   console.log("config.extra: {{ config.extra }}");
   console.log("config.extra.READTHEDOCS: {{ config.extra.READTHEDOCS }}");
   console.log("config.extra.READTHEDOCS_VERSION: {{ config.extra.READTHEDOCS_VERSION }}");
   

   should print something similar to this in the browser console:

   config.extra: {'READTHEDOCS': True, 'READTHEDOCS_VERSION': 1.2.3, 'READTHEDOCS_PROJECT': openvidu}
   config.extra.READTHEDOCS: True
   config.extra.READTHEDOCS_VERSION: 1.2.3
   

Actual Result

1. The cat mkdocs.yml build step shows that READTHEDOCS, READTHEDOCS_VERSION, and READTHEDOCS_PROJECT are all null:

   extra:
     READTHEDOCS: null
     READTHEDOCS_PROJECT: null
     READTHEDOCS_VERSION: null
   

2. The browser console shows this output:

   config.extra: {'READTHEDOCS': None, 'READTHEDOCS_PROJECT': None, 'READTHEDOCS_VERSION': None}
   config.extra.READTHEDOCS: None
   config.extra.READTHEDOCS_VERSION: None
   

Extra

Question / potential extra bug in the documentation: the technique shown in How do I change behavior when building with Read the Docs? would not really work with MkDocs, would it?

The sample is:

{% if READTHEDOCS %}
Woo
{% endif %}

but in MkDocs the READTHEDOCS is not directly available, is it expected to be? (sorry to ask here but is just a yes/no question that seems very relevant given the topic of the issue)

[j1elo]

Hi,

It seems this is the only actionable item from this issue for now.

I guess an additional one was suggested from these sentences, but was never stated as a proper actionable item:

• the !ENV syntax is not recognized. Unfortunately, I don’t think there is a workaround, currently.

• This may be solved by our “Future builders” (https://github.com/readthedocs/readthedocs.org/pull/8190) because we may not require a safe YAML loader when it gets implemented.

• For the !ENV case, we could use a similar solution than for !! in https://github.com/readthedocs/readthedocs.org/issues/7461

Which I’d take to become either of:

• !ENV syntax support addition.
• Workaround provided for usage of such syntax.
• Decision taken about whether the “may” is to become a “will” in the phrase may be solved by our “Future builders” (this sounds to me like the best option, if those Future builders are actually going to become a reality at some point)
• Follow the trail of a “similar solution than for !!” and see if the same ideas can actually be applied.

[humitos]

Hi @j1elo! Thanks for replying. You have mentioned here some interesting points that have been in our discussions lately but we haven’t yet had the time to fix them.

Thank you for the feedback. So far I’ve been left with the only choice of loading the (otherwise undocumented!) script readthedocs-data.js

This is not documented on purpose because we don’t expect users to use this data as it may change without communication. I don’t think it has changed in years now. However, we can’t compromise ourselves on that.

This bring the next followup question, not sure if worth a separate bug report: why the RTD context injection is not working either?

All the pages under /development/design/ are documents that we used to discuss proposed features. Some of them were never implemented --as the Theme Context that you just found 😞 . We have discussed not exposing these pages to users or moving them to a different set of documentation because we have already faced the confusion you are experimenting.

Seems to me that the general state of MkDocs support in RTD is pretty weak, as soon as you try to do anything beyond the most basic use cases

Unfortunately, this is true. Due to security restrictions, there are advanced MkDocs configurations that we cannot support currently and we haven’t had the time to change our internal implementation to reduce those risks. For the !ENV case, we could use a similar solution than for !! in https://github.com/readthedocs/readthedocs.org/issues/7461

no problem with that, but I do believe that adding appropriate comments in some of these doc pages would save long hours of frustration to users (at least I know it would have for me…)

I’m sorry to read that. I hope we can clarify these limitations in our documentation. @astrojuanlu what do you think about mentioning that non-standard (or advanced) YAML usage is not supported currently?