Repository: yt-project/yt

Issue:
DOC: "note" markup is leaking
### Bug report

**Bug summary**

As was brought up on Slack by @chummels , our latest docs build has many broken pages where `note..` blocks tend to leak to the rest of the page

for instance: 
https://yt-project.org/docs/dev/developing/creating_derived_fields.html
![](https://user-images.githubusercontent.com/14075922/230574540-509530a1-46d5-4791-a93d-8d87046d3320.png)


At the moment, this is only affect the *dev* version of documentation, the stable version is still okay, see https://yt-project.org/doc/developing/creating_derived_fields.html

It also looks like there's a *different* bug in the latest docs builds that were associated with recent PRs, see for instance: https://tests.yt-project.org/job/yt_docs_new/2529/artifact/doc/build/html/developing/creating_derived_fields.html

![Screenshot 2023-04-07 at 10 46 48](https://user-images.githubusercontent.com/14075922/230576305-32cb2d15-c06b-420f-8d1b-51b57940ef83.png)

Since there wasn't any active change on our part, it seems that the most likely explanation is that some of our docs-only dependency has changed (wether it's an intended change or a bug remains to be seen).

I'm not sure exactly how old the current stable version of the website is. It's at most as old as yt 4.1.0 (October 7th 2022) and at most as recent as yt 4.1.4 (January 21th 2023).


It'd be great to see if we can fix that in time for our next release.


Discussion:
Notably, the `warning::`  statement in sphinx docs doesn’t seem to suffer from the same issues as `note::` (see: https://yt-project.org/docs/dev/reference/configuration.html#configuration-options-at-runtime), so one simple fix would be to change all the `note::` instances to `warning::` instances.  I don’t really like this solution, but it would work until the upstream issue is addressed.
I think it does though?  Here's the source, and the image...

```
.. warning:: Several parameters are only accessed when yt starts up: therefore,
   if you want to modify any configuration parameters at runtime, you should
   execute the appropriate commands at the *very top* of your script!

This involves importing the configuration object and then setting a given
parameter to be equal to a specific string.  Note that even for items that
accept integers, floating points and other non-string types, you *must* set
them to be a string or else the configuration object will consider them broken.

```

![Screenshot from 2023-04-07 12-18-28](https://user-images.githubusercontent.com/89019/230650307-be4970ea-ff98-4b7d-8429-db6c5b927433.png)

Summarizing notes from slack discussion:

This seems to ultimately come from an issue in `docutils >= 0.18` with certain sphinx versions https://github.com/sphinx-doc/sphinx/issues/10121 (thanks @yut23  for pointing that out!)

In particular, it was exposed in yt's docs now because (1) `sphinx-rtd-theme` added support for `docutils` 0.18 with the recent 1.2 release and (2)  `sphinx` didn't start pinning `docutils` til version 3.5.4 ([link](https://www.sphinx-doc.org/en/master/changes.html#release-3-5-4-released-apr-11-2021)) and we're using 3.1.2, so `docutils` was updating to the latest version with the `sphinx-rtd-theme` 1.2 release. 

Simply pinning `docutils<0.18` resolved the issue for me locally... so that's probably the quickest short term fix. But maybe it's worth trying to update the sphinx version at least to the latest in the 3.x series? That would actually further limit docutils to 0.16.

 
Thanks a lot for this deep dive !
> Simply pinning docutils<0.18 resolved the issue for me locally... so that's probably the quickest short term fix. But maybe it's worth trying to update the sphinx version at least to the latest in the 3.x series? That would actually further limit docutils to 0.16.

👍🏻 on this. Let's try upgrading sphinx first and if that doesn't work, let's pin docutils 

I tried bumping Sphinx to 3.5.4 (last version in the 3.x series), to 6.1.3 (latest), and independently, pinned docutils<0.18, and I can't see any difference in how note blocks are rendered. I'm a bit lost.
Take 2: I was able to reproduce the bug locally, and saw that upgrading sphinx to 3.5.4 resolved it. What I still don't understand is why docs build on Jenkins behave differently.

Resolving patch:
diff --git a/yt/data_objects/static_output.py b/yt/data_objects/static_output.py
--- a/yt/data_objects/static_output.py
+++ b/yt/data_objects/static_output.py
@@ -184,6 +184,7 @@ class Dataset(abc.ABC):
     field_units: Optional[Dict[AnyFieldKey, Unit]] = None
     derived_field_list = requires_index("derived_field_list")
     fields = requires_index("fields")
+    conversion_factors: Optional[Dict[str, float]] = None
     # _instantiated represents an instantiation time (since Epoch)
     # the default is a place holder sentinel, falsy value
     _instantiated: float = 0
@@ -273,7 +274,7 @@ def __init__(
         if self._instantiated != 0:
             return
         self.dataset_type = dataset_type
-        self.conversion_factors: Dict[str, float] = {}
+        self.conversion_factors = {}
         self.parameters: Dict[str, Any] = {}
         self.region_expression = self.r = RegionExpression(self)
         self.known_filters = self.known_filters or {}


Test patch: