Skip to content

Commit 9915a01

Browse files
authored
update version JSON config guidance (#1393)
1 parent cff064c commit 9915a01

File tree

1 file changed

+7
-6
lines changed

1 file changed

+7
-6
lines changed

docs/user_guide/version-dropdown.rst

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ save the JSON file.
7676
Configure ``switcher['json_url']``
7777
----------------------------------
7878

79-
The JSON file needs to be at a stable, persistent, fully-resolved URL (i.e.,
79+
*The JSON file needs to be at a stable, persistent, fully-resolved URL* (i.e.,
8080
not specified as a path relative to the sphinx root of the current doc build).
8181
Each version of your documentation should point to the same URL, so that as new
8282
versions are added to the JSON file all the older versions of the docs will
@@ -101,11 +101,6 @@ in a few different ways:
101101
only the most recent version is ever loaded (even by older versions of the
102102
docs).
103103

104-
- The JSON could be saved in a folder that is listed under your site's
105-
``html_static_path`` configuration. See `the Sphinx static path documentation
106-
<https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path>`_
107-
for more information.
108-
109104
- The JSON could be stored outside the doc build trees. This probably means it
110105
would be outside the software repo, and would require you to add new version
111106
entries to the JSON file manually as part of your release process. Example:
@@ -119,6 +114,12 @@ in a few different ways:
119114
}
120115
}
121116
117+
- In theory the JSON could be saved in a folder that is listed under your site's
118+
``html_static_path`` configuration, **but this is not recommended**. If you want to
119+
do it this way, see `the Sphinx static path documentation
120+
<https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path>`_
121+
for more information but do so knowing that we do not support this use case.
122+
122123
By default, the theme is testing the :code:`.json` file provided and outputs warnings in the Sphinx build. If this test breaks the pipeline of your docs, the test can be disabled by configuring the :code:`check_switcher` parameter in :code:`conf.py`:
123124

124125
.. code-block:: python

0 commit comments

Comments
 (0)