# Copyright The PyTorch Lightning team.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from docutils import nodes
from docutils.parsers.rst import Directive
from docutils.statemachine import StringList

ADMONITION_TEMPLATE = """
.. raw:: html

    <div class="admonition warning {type}">
    <p class="admonition-title">{title}</p>
    <p>This {scope} is currently in Beta. The interfaces and functionality may change without warning in future
    releases.</p>
    </div>
"""


class Beta(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0

    def run(self):

        scope = self.arguments[0]

        admonition_rst = ADMONITION_TEMPLATE.format(type="beta", title="Beta", scope=scope)
        admonition_list = StringList(admonition_rst.split("\n"))
        admonition = nodes.paragraph()
        self.state.nested_parse(admonition_list, self.content_offset, admonition)
        return [admonition]


def setup(app):
    app.add_directive("beta", Beta)

docs/extensions/stability.py
# Copyright The PyTorch Lightning team.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from docutils import nodes
from docutils.parsers.rst import Directive
from docutils.statemachine import StringList

ADMONITION_TEMPLATE = """
.. raw:: html

    <div class="admonition warning {type}">
    <p class="admonition-title">{title}</p>
    <p>

This {scope} is currently in Beta. The API and functionality may change without warning in future
releases. :ref:`More details <stability>`.

.. raw:: html

    </p>
    </div>
"""


class Beta(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0

    def run(self):

        scope = self.arguments[0]

        admonition_rst = ADMONITION_TEMPLATE.format(type="beta", title="Beta", scope=scope)
        admonition_list = StringList(admonition_rst.split("\n"))
        admonition = nodes.paragraph()
        self.state.nested_parse(admonition_list, self.content_offset, admonition)
        return [admonition]


def setup(app):
    app.add_directive("beta", Beta)

docs/extensions/stability.py
diff --git a/docs/extensions/stability.py b/docs/extensions/stability.py
index d22408c9f0..057afa9c97 100644
--- a/docs/extensions/stability.py
+++ b/docs/extensions/stability.py
@@ -20,8 +20,14 @@
 
     <div class="admonition warning {type}">
     <p class="admonition-title">{title}</p>
-    <p>This {scope} is currently in Beta. The interfaces and functionality may change without warning in future
-    releases.</p>
+    <p>
+
+This {scope} is currently in Beta. The API and functionality may change without warning in future
+releases. :ref:`More details <stability>`.
+
+.. raw:: html
+
+    </p>
     </div>
 """
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3d50304506..5512441ca7 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -144,6 +144,7 @@ Lightning Flash
    :caption: Community
 
    governance
+   stability
    generated/CONTRIBUTING.md
    generated/CHANGELOG.md
 
diff --git a/docs/source/stability.rst b/docs/source/stability.rst
new file mode 100644
index 0000000000..d18a5d2f1b
--- /dev/null
+++ b/docs/source/stability.rst
@@ -0,0 +1,26 @@
+.. _stability:
+
+Flash API Stability
+===================
+
+We classify all features within Flash as either stable or in beta.
+Beta features are explicitly labelled, all remaining features can be viewed as stable.
+This document is intended to help you know what to expect and to outline our commitment to stability.
+
+Stable
+______
+
+For stable features, all of the following are true:
+
+- the API isn’t expected to change
+- if anything does change, incorrect usage will give a deprecation warning for **one major release** before the breaking change is made
+
+Beta
+____
+
+For beta features, any or all of the following may be true:
+
+- the feature has unstable dependencies
+- the API may change without notice in future versions
+- the performance of the feature has not been verified
+- the docs for this feature are under active development

Docs page describing Beta meaning
## 📚 Documentation

Add a page in our docs describing that beta means that one or all of the following are true:
- the feature has unstable dependencies
- the feature may change without notice in future versions
- the feature is not compatible with other flash / pl features
- the performance of the feature has not been verified

Anything else?

