Explore an alternative way of explaining states

docs/user/automation-rules.rst

@@ -73,11 +73,11 @@ Hide version
 
 Make version public
   Sets the version's privacy level to public.
-  See :ref:`versions:Privacy levels`.
+  See :ref:`versions:Version states`.
 
 Make version private
   Sets the version's privacy level to private.
-  See :ref:`versions:Privacy levels`.
+  See :ref:`versions:Version states`.
 
 Set version as default
   Sets the version as the :term:`default version`.

docs/user/commercial/privacy-level.rst

@@ -17,4 +17,4 @@ and changing :guilabel:`Privacy level` to `Public`.
 .. note::
 
    To control access to the documentation itself,
-   see :ref:`versions:privacy levels`.
+   see :ref:`versions:Version states`.

docs/user/commercial/sharing.rst

@@ -35,8 +35,6 @@ Enabling sharing
 
    You can always revoke access in the same panel.
 
-Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
-
 Sharing methods
 ---------------
 

docs/user/commercial/single-sign-on.rst

@@ -13,8 +13,6 @@ Currently, we support two different types of single sign-on:
 * Authentication *and* authorization are managed by the identity provider (GitHub, Bitbucket or GitLab)
 * Authentication (*only*) is managed by the identity provider (Google Workspace account with a verified email address)
 
-Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
-
 .. _sso_git_provider:
 
 Single Sign-on with GitHub, Bitbucket, or GitLab

docs/user/guides/best-practice/links.rst

@@ -62,7 +62,7 @@ Good practice ✅
   Renaming an article's title is great for the reader and great for SEO,
   but this does not have to involve the URL.
 * Establish your understanding of the *latest* and :term:`default version` of your documentation at the beginning. Changing their meaning is very disruptive to incoming links.
-* Keep development versions :ref:`hidden <versions:Hidden>` so people do not find them on search engines by mistake.
+* Keep development versions :ref:`hidden <versions:Version states>` so people do not find them on search engines by mistake.
   This is the best way to ensure that nobody links to URLs that are intended for development purposes.
 * Use a :ref:`version warning <versions:Version warning>` to ensure the reader is aware in case they are reading an old (archived) version.
 

docs/user/guides/content/index.rst

@@ -73,5 +73,4 @@ How-to guides: content, themes and SEO
    Using Jupyter notebooks in Sphinx </guides/jupyter>
    Migrating from rST to MyST </guides/migrate-rest-myst>
    Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>
-   Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>
    Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>

docs/user/guides/pull-requests.rst

@@ -48,7 +48,7 @@ To change the privacy level:
 #. Select your option in :guilabel:`Privacy level of builds from pull requests`
 #. Click on :guilabel:`Save`
 
-Privacy levels work the same way as :ref:`normal versions <versions:privacy levels>`.
+Privacy levels work the same way as :ref:`normal versions <versions:Version states>`.
 
 Limitations
 -----------

docs/user/reference/robots.rst

@@ -11,7 +11,7 @@ It's useful for:
 Read the Docs automatically generates one for you with a configuration that works for most projects.
 By default, the automatically created ``robots.txt``:
 
-* Hides versions which are set to :ref:`versions:Hidden` from being indexed.
+* Hides versions which are set to :ref:`versions:Version states` from being indexed.
 * Allows indexing of all other versions.
 
 .. warning::

docs/user/server-side-search/api.rst

@@ -158,7 +158,7 @@ to include results from subprojects use the ``subprojects`` paramater.
 Authentication and authorization
 --------------------------------
 
-If you are using :ref:`private versions <versions:privacy levels>`,
+If you are using :ref:`private versions <versions:Version states>`,
 users will only be allowed to search projects they have permissions over.
 Authentication and authorization is done using the current session,
 or any of the valid :doc:`sharing methods </commercial/sharing>`.

docs/user/tutorial/index.rst

@@ -415,7 +415,7 @@ and that's why the URLs of your HTML documentation contain the string ``/latest/
 Creating a new version of your documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Read the Docs automatically creates documentation versions from GitHub branches and tags that :ref:`follows some rules <versions:how we envision versions working>` about looking like version numbers, such as ``1.0``, ``2.0.3`` or ``4.x``.
+Read the Docs automatically creates documentation versions from GitHub branches and tags that :ref:`follows some rules <versions:Versioning workflows>` about looking like version numbers, such as ``1.0``, ``2.0.3`` or ``4.x``.
 
 To create version ``1.0`` of your code, and consequently of your documentation:
 
@@ -472,7 +472,7 @@ To activate the ``1.0.x`` version:
 
 .. note::
 
-   Read more about :ref:`hidden versions <versions:hidden>`
+   Read more about :ref:`hidden versions <versions:Version states>`
    in our documentation.
 
 .. "Show a warning for old versions" feature is not available anymore.

docs/user/versions.rst

@@ -1,132 +1,64 @@
 Versions
 ========
 
-Read the Docs supports multiple versions of your documentation.
-On initial import,
-we will create a ``latest`` version.
-This will point at the default branch defined in your Git repository.
-(by default, ``main``).
+Read the Docs supports publishing multiple versions of your documentation
+at the same time.
+On initial import, we will create a ``latest`` version
+that points to the default branch defined in your Git repository.
 
 If your project has any tags or branches with a name following `semantic versioning <https://semver.org/>`_,
-we also create a ``stable`` version, tracking your most recent release.
+we also create a ``stable`` version tracking your most recent release.
 If you want a custom ``stable`` version,
 create either a tag or branch in your project with that name.
 
 When you have :doc:`/integrations` configured for your repository,
 we will automatically build each version when you push a commit.
 
-How we envision versions working
---------------------------------
-
-In the normal case,
-the ``latest`` version will always point to the most up to date development code.
-If you develop on a branch that is different than the default for your VCS,
-you should set the **Default Branch** to that branch.
-
-You should push a **tag** for each version of your project.
-These tags should be numbered in a way that is consistent with semantic versioning.
-This will map to your ``stable`` branch by default.
-
-.. note::
-    We in fact are parsing your tag names against the rules given by
-    `PEP 440`_. This spec allows "normal" version numbers like ``1.4.2`` as
-    well as pre-releases. An alpha version or a release candidate are examples
-    of pre-releases and they look like this: ``2.0a1``.
-
-    We only consider non pre-releases for the ``stable`` version of your
-    documentation.
-
-If you have documentation changes on a **long-lived branch**,
-you can build those too.
-This will allow you to see how the new docs will be built in this branch of the code.
-Generally you won't have more than 1 active branch over a long period of time.
-The main exception here would be **release branches**,
-which are branches that are maintained over time for a specific release number.
-
-.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
-
 Version states
 --------------
 
-States define the visibility of a version across the site.
-You can change the states of a version from the :guilabel:`Versions` tab of your project.
-
-Active
-~~~~~~
+Each version of your documentation has a combination of three states (**Active**, **Public**, and **Hidden**) which determine its visibility on your site:
 
-- **Active**
+You can change the states for each version of your documentation in the :guilabel:`Versions` tab of your project.
 
-  - Docs for this version are visible
-  - Builds can be triggered for this version
+**Active** or **Inactive**
+  - **Active** docs are visible, and builds can be triggered for the documentation.
+  - Docs for **Inactive** versions *are deleted* and builds cannot be triggered.
 
-- **Inactive**
+**Hidden** or **Not hidden**
+  - **Hidden** docs are not listed on the :term:`flyout menu` on the docs site,
+    or shown in search results from another version on the docs site
+    (like on search results from a superproject).
+  - **Not hidden** docs are listed on the :term:`flyout menu` on the docs site,
+    and are shown in search results on the docs site.
 
-  - Docs for this version aren't visible
-  - Builds can't be triggered for this version
+  Hiding a version doesn't make it private,
+  any user with a link to its docs can still see it.
+  This is useful when:
 
-When you deactivate a version, its docs are removed.
+  - You no longer support a version, but you don't want to remove its docs.
+  - You have a work in progress version and don't want to publish its docs just yet.
 
-Hidden
-~~~~~~
+  Hidden verions are listed as ``Disallow: /path/to/version/``
+  in the default `robots.txt file <https://www.robotstxt.org/>`__ created by Read the Docs.
 
-- **Not hidden and Active**
+**Public** or **Private** (only available on on :doc:`/commercial/index`)
+  - Public versions are visible to everyone.
+  - Private versions are available only to people who have permissions to see them.
+    They will not display on any list view, and will 404 when visted by people without viewing permissions.
+    If you want to share your docs temporarily, see :doc:`/commercial/sharing`.
 
-  - This version is listed on the :term:`flyout menu` on the docs site
-  - This version is shown in search results on the docs site
-
-- **Hidden and Active**
-
-  - This version isn't listed on the :term:`flyout menu` on the docs site
-  - This version isn't shown in search results from another version on the docs site
-    (like on search results from a superproject)
-
-Hiding a version doesn't make it private,
-any user with a link to its docs would be able to see it.
-This is useful when:
-
-- You no longer support a version, but you don't want to remove its docs.
-- You have a work in progress version and don't want to publish its docs just yet.
-
-.. note::
-
-   Active versions that are hidden will be listed as ``Disallow: /path/to/version/``
-   in the default `robots.txt file <https://www.robotstxt.org/>`__ created by Read the Docs.
-
-Privacy levels
---------------
-
-.. note::
-
-   Privacy levels are only supported on :doc:`/commercial/index`.
-
-Public
-~~~~~~
-
-It means that everything is available to be seen by everyone.
-
-Private
-~~~~~~~
-
-Private versions are available only to people who have permissions to see them.
-They will not display on any list view, and will 404 when you link them to others.
-If you want to share your docs temporarily, see :doc:`/commercial/sharing`.
-
-In addition, if you want other users to view the build page of your public versions,
-you'll need to the set the :doc:`privacy level of your project </commercial/privacy-level>` to public.
-
-Logging out
-'''''''''''
-
-When you log in to a documentation site, you will be logged in until close your browser.
-To log out, click on the :guilabel:`Log out` link in your documentation's :term:`flyout menu`.
-This is usually located in the bottom right or bottom left, depending on the theme design.
-This will log you out from the current domain,
-but not end any other session that you have active.
+    In addition, if you want other users to view the build page of your public versions,
+    you'll need to the set the :doc:`privacy level of your project </commercial/privacy-level>` to public.
 
 Tags and branches
 -----------------
 
-Read the Docs supports two workflows for versioning: based on tags or branches.
+Read the Docs supports two workflows for versioning:
+
+- based on tags
+- based on branches
+
 If you have at least one tag,
 tags will take preference over branches when selecting the stable version.
 
@@ -160,3 +92,26 @@ for example ``https://pip.readthedocs.io/``,
 they will be redirected to the **Default version**.
 This defaults to **latest**,
 but could also point to your latest released version.
+
+Versioning workflows
+--------------------
+
+RTD makes certain assumptions about your documentation version defaults,
+all of which can be reconfigured if you need to:
+
+- ``latest`` version points to the most up to date development code.
+  If you develop on a branch that is different than the default for your version control system,
+  set the **Default Branch** to the branch you use.
+
+- **tags** are semantic versioning compatible (according to  `PEP 440`_) snapshots
+  of your documentation. The most recent semantic tag maps to the ``stable`` tag.
+
+  Semantic versioning allows "normal" version numbers like ``1.4.2``, as
+  well as pre-releases like this: ``2.0a1``. The ``stable`` version of your documentation never includes a pre-release.
+
+- If you have documentation changes on a **long-lived branch**,
+  you can build those too, to see how the new docs will be built.
+  Generally you won't have more than 1 active branch over a long period of time,
+  apart from **release branches**, maintained over time for a specific release.
+
+.. _PEP 440: https://www.python.org/dev/peps/pep-0440/