From 6bb3ef73dcc43d1e78bd928f465500207480c090 Mon Sep 17 00:00:00 2001
From: Benjamin Bach <benjamin@readthedocs.org>
Date: Thu, 26 Jan 2023 14:03:47 +0100
Subject: [PATCH] Relabel badges as feature reference, add a syntax section and
 something about badges for private projects

---
 docs/user/badges.rst             | 28 ++++++++++++++++++++++++++--
 docs/user/index.rst              |  1 -
 docs/user/reference/features.rst |  1 +
 3 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/user/badges.rst b/docs/user/badges.rst
index afb7ea62df7..adfdaf8d538 100644
--- a/docs/user/badges.rst
+++ b/docs/user/badges.rst
@@ -21,6 +21,18 @@ An example of each is shown here:
 
 |green| |nbsp| |red| |nbsp| |yellow|
 
+Automatically generated
+-----------------------
+
+On the dashboard of a project, an example badge is displayed
+together with code snippets for reStructuredText, Markdown, and HTML.
+
+Badges are generated on-demand for all Read the Docs projects, using the following URL syntax:
+
+.. code-block:: text
+
+   https://readthedocs.org/projects/<project-slug>/badge/?version=<version>&style=<style>
+
 Style
 -----
 
@@ -56,9 +68,11 @@ You can change the version of the documentation your badge points to.
 To do this, you can pass the ``version`` GET argument to the badge URL.
 By default, it will point at the *default version* you have specified for your project.
 
-The badge URL looks like this::
+The badge URL looks like this:
 
-    https://readthedocs.org/projects/docs/badge/?version=latest
+.. code-block:: text
+
+    https://readthedocs.org/projects/<project-slug>/badge/?version=latest
 
 
 Badges on dashboard pages
@@ -75,3 +89,13 @@ to make embedding it easier.
 .. |yellow| image:: https://assets.readthedocs.org/static/projects/badges/unknown-flat.svg
 .. |nbsp| unicode:: 0xA0
    :trim:
+
+
+Badges for private projects
+---------------------------
+
+.. include:: /shared/admonition-rtd-business.rst
+
+For private projects, a badge URL cannot be guessed.
+A token is needed to display it.
+Private badge URLs are displayed on a private project's dashboard in place of public URLs.
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 667b24ae713..a4d60716ef1 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -161,7 +161,6 @@ and some of the core features of Read the Docs.
    /build-customization
    /build-troubleshooting
    /environment-variables
-   /badges
 
    /support
 
diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst
index 73c79ddc212..448bd96454a 100644
--- a/docs/user/reference/features.rst
+++ b/docs/user/reference/features.rst
@@ -8,3 +8,4 @@ Features
 
    analytics
    /server-side-search/index
+   /badges