Add warning to top of latest docs

gtalarico · Aug 6, 2023 · 9b30651 · 9b30651
1 parent f203ac9
commit 9b30651
Show file tree

Hide file tree

Showing 10 changed files with 43 additions and 10 deletions.
diff --git a/docs/source/substitutions.rst → docs/source/_substitutions.rst b/docs/source/substitutions.rst → docs/source/_substitutions.rst
diff --git a/docs/source/_warn_latest.rst b/docs/source/_warn_latest.rst
@@ -0,0 +1,7 @@
+.. only:: readthedocs_latest
+
+   .. warning::
+
+      This documentation was generated for an unreleased build of pyAirtable,
+      and might describe unreleased features. For the latest released version, see
+      https://pyairtable.readthedocs.io/en/stable/
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -1,4 +1,6 @@
-.. include:: substitutions.rst
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
 
 API Reference
 =============

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -9,6 +9,10 @@
 import pyairtable.orm.fields
 from pyairtable import __version__ as version
 
+if typing.TYPE_CHECKING:
+    import sphinx.util.tags
+
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
@@ -80,6 +84,14 @@ def typehints_formatter(annotation, config):
 suppress_warnings = ["autoapi.python_import_resolution"]
 
 
+# This allows us to insert a warning on the 'latest' build; see _warn_latest.rst
+# and https://www.sphinx-doc.org/en/master/usage/configuration.html#conf-tags
+# and https://docs.readthedocs.io/en/stable/reference/environment-variables.html
+if _rtfd_version := os.environ.get("READTHEDOCS_VERSION"):
+    tags: "sphinx.util.tags.Tags"  # this is just to help type-checking IDEs
+    tags.add(f"readthedocs_{_rtfd_version}")  # noqa
+
+
 ################################
 # CUSTOM
 ################################

diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
@@ -1,11 +1,11 @@
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
 
 Getting Started
 ======================================
 
 
-.. include:: substitutions.rst
-
-
 Installation
 ------------
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,5 +1,7 @@
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
 .. image:: _static/logo.svg
-.. include:: substitutions.rst
 
 pyAirtable
 ==========
@@ -14,7 +16,7 @@ pyAirtable
    `GitHub <https://github.com/gtalarico/pyairtable>`_
 
 
-   Latest Release: |version|
+   Version: |version|
 
 
 .. toctree::

diff --git a/docs/source/metadata.rst b/docs/source/metadata.rst
@@ -1,4 +1,6 @@
-.. include:: substitutions.rst
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
 
 Metadata
 ==============

diff --git a/docs/source/migrations.rst b/docs/source/migrations.rst
@@ -1,3 +1,7 @@
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
+
 Migration Guide
 *****************
 

diff --git a/docs/source/orm.rst b/docs/source/orm.rst
@@ -1,4 +1,6 @@
-.. include:: substitutions.rst
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
 
 ORM
 ==============

diff --git a/docs/source/tables.rst b/docs/source/tables.rst
@@ -1,8 +1,10 @@
+.. include:: _warn_latest.rst
+.. include:: _substitutions.rst
+
+
 Working with Tables
 ==============================
 
-.. include:: substitutions.rst
-
 
 .. note::
     Airtable imposes a `rate limit <https://airtable.com/developers/web/api/rate-limits>`__