Docs: New entries to glossary (#10249)

* Adds "reproducible" to glossary

* Adds glossary entries from #10071

* Make "webhook" respect a-z

* Improve reproducible entry

* Simplify the definition so its easier to understand

* Move root URL so it's a-z

* Remove "profile page"

* Add "pinning" to glossary

* Apply suggestions from @stsewd and @humitos code review

Co-authored-by: Manuel Kaufmann <[email protected]>
Co-authored-by: Santos Gallegos <[email protected]>

* Update docs/user/glossary.rst

Co-authored-by: Manuel Kaufmann <[email protected]>

* Put defining sentence first

* Add some references to new glossary entries

* Put definition first

* Add more references to pinning

---------

Co-authored-by: Manuel Kaufmann <[email protected]>
Co-authored-by: Santos Gallegos <[email protected]>

Author: 3 people

docs/user/build-notifications.rst

@@ -9,7 +9,7 @@ Email notifications:
   This makes sure you know when your builds have failed.
 
 Build Status Webhooks:
-  Build notifications can happen via webhooks.
+  Build notifications can happen via :term:`webhooks <webhook>`.
   This means that we are able to support a wide variety of services that receive notifications.
 
   Slack and Discord are supported through ready-made templates.

docs/user/connected-accounts.rst

@@ -88,7 +88,7 @@ which allow us to build your documentation on every change to your repository.
           We ask for this so you can create a Read the Docs account and login with your GitHub credentials.
 
       Administering webhooks (``admin:repo_hook``)
-          We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
+          We ask for this so we can create :term:`webhooks <webhook>` on your repositories when you import them into Read the Docs.
           This allows us to build the docs when you push new commits.
 
       Read access to your organizations (``read:org``)
@@ -115,7 +115,7 @@ which allow us to build your documentation on every change to your repository.
       We request permissions for:
 
       Administering your repositories (``repository:admin``)
-        We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
+        We ask for this so we can create :term:`webhooks <webhook>` on your repositories when you import them into Read the Docs.
         This allows us to build the docs when you push new commits.
         NB! This permission scope does **not** include any write access to code.
 

docs/user/faq.rst

@@ -354,7 +354,7 @@ and as a result, it tends to look a bit better with the default theme.
 I need to install a package in a environment with pinned versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To ensure proper installation of a Python package, the ``pip`` :ref:`install method <config-file/v2:python.install>` will automatically upgrade every dependency to its most recent version in case they aren't pinned by the package definition.
+To ensure proper installation of a Python package, the ``pip`` :ref:`install method <config-file/v2:python.install>` will automatically upgrade every dependency to its most recent version in case they aren't:term:`pinned <pinning>` by the package definition.
 If instead you'd like to pin your dependencies outside the package, you can add this line to your requirements or environment file (if you are using Conda).
 
 In your ``requirements.txt`` file::

docs/user/glossary.rst

@@ -6,6 +6,11 @@ so that you have a reference for how we're using them.
 
 .. glossary::
 
+   CI/CD
+      CI/CD is a common way to write *Continuous Integration and Continuous Deployment*.
+      In some scenarios, they exist as two separate platforms.
+      Read the Docs is a combined CI/CD platform made for documentation.
+
    dashboard
       The "admin" site where Read the Docs projects are managed and configured.
       This varies for our two properties:
@@ -39,36 +44,97 @@ so that you have a reference for how we're using them.
       and rules for publication of documentation can be :doc:`automated </automation-rules>`.
       Similar to :term:`Docs as Code`.
 
+   pinning
+      To *pin* a requirement means to explicitly specify which version should be used.
+      *Pinning* software requirements is the most important technique to make a project :term:`reproducible`.
+
+      When documentation builds,
+      software dependencies are installed in their latest versions permitted by the pinning specification.
+      Since software packages are frequently released,
+      we are usually trying to avoid incompatibilities in a new release from suddenly breaking a documentation build.
+
+      Examples of Python dependencies::
+
+          # Exact pinning: Only allow Sphinx 5.3.0
+          sphinx==5.3.0
+
+          # Loose pinning: Lower and upper bounds result in the latest 5.3.x release
+          sphinx>=5.3,<5.4
+
+          # Very loose pinning: Lower and upper bounds result in the latest 5.x release
+          sphinx>=5,<6
+
+      Read the Docs recommends using **exact pinning**.
+
+      See: :doc:`/guides/reproducible-builds`.
+
    pre-defined build jobs
       Commands executed by Read the Docs when performing the build process.
       They cannot be overwritten by the user.
 
-   profile page
-      Page where you can see the projects of a certain user.
-
    project home
       Page where you can access all the features of Read the Docs,
       from having an overview to browsing the latest builds or administering your project.
 
    project page
       Another name for :term:`project home`.
 
+   reproducible
+      A documentation project is said to be *reproducible* when its sources build correctly on Read the Docs over a periode of many years.
+      You can also think of being *reproducible* as being *robust* or *resillient*.
+
+      Being "reproducible" is an important positive quality goal of documentation.
+
+      When builds are not reproducible and break due to external factors,
+      they need frequent troubleshooting and manual fixing.
+
+      The most common external factor is that new versions of software dependencies are released.
+
+      See: :doc:`/guides/reproducible-builds`.
+
+   root URL
+      Home URL of your documentation without the ``/<lang>`` and ``/<version>`` segments.
+      For projects without custom domains, the one ending in ``.readthedocs.io/``
+      (for example, ``https://docs.readthedocs.io`` as opposed to ``https://docs.readthedocs.io/en/latest``).
+
    slug
       A unique identifier for a project or version. This value comes from the
       project or version name, which is reduced to lowercase letters, numbers,
       and hyphens. You can retrieve your project or version slugs from
       :doc:`our API <api/v3>`.
 
+   static website
+      A static site or static website is a collection of HTML files, images, CSS and JavaScript that are served statically,
+      as opposed to dynamic websites that generate a unique response for each request, using databases and user sessions.
+
+      Static websites are highly portable, as they do not depend on the webserver.
+      They can also be viewed offline.
+
+      Documentation projects served on Read the Docs are *static websites*.
+
+      Tools to manage and generate static websites are commonly known as *static site generators* and there is a big overlap with documentation tools.
+      Some static site generators are also documentation tools,
+      and some documentation tools are also used to generate normal websites.
+
+      For instance, :doc:`Sphinx <sphinx:index>` is made for documentation but also used for blogging.
+
    subproject
       Project A can be configured such that when requesting a URL ``/projects/<subproject-slug>``,
       the root of project B is returned.
       In this case, *project B* is the subproject.
       Read more in :doc:`/subprojects`.
 
-   root URL
-      Home URL of your documentation without the ``/<lang>`` and ``/<version>`` segments.
-      For projects without custom domains, the one ending in ``.readthedocs.io/``
-      (for example, ``https://docs.readthedocs.io`` as opposed to ``https://docs.readthedocs.io/en/latest``).
-
    user-defined build jobs
       Commands defined by the user that Read the Docs will execute when performing the build process.
+
+   webhook
+      A webhook is a special URL that can be called from another service,
+      usually with a secret token.
+      It is commonly used to start a build or a deployment or to send a status update.
+
+      There are two important types of webhooks for Read the Docs:
+
+      * Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds.
+      * Read the Docs has a unique webhook for each project that the Git provider calls when changes happen in Git.
+
+      See also: :doc:`/guides/git-integrations` and :doc:`/build-notifications`

docs/user/guides/build-notifications.rst

@@ -6,7 +6,7 @@ Build notifications can alert you when your builds fail so you can take immediat
 
 .. note::
 
-   Currently we don't send notifications or trigger webhooks
+   Currently we don't send notifications or trigger :term:`webhooks <webhook>`
    on :doc:`builds from pull requests </pull-requests>`.
 
 

docs/user/guides/git-integrations.rst

@@ -114,7 +114,7 @@ Provider-specific instructions
 Additional integration
 ----------------------
 
-You can configure multiple webhooks.
+You can configure multiple :term:`webhooks <webhook>`.
 
 To manually set up an integration, go to :guilabel:`Admin` > :guilabel:`Integrations` >  :guilabel:`Add integration`
 dashboard page and select the integration type you'd like to add.

docs/user/guides/reproducible-builds.rst

@@ -2,7 +2,7 @@ How to create reproducible builds
 =================================
 
 Your documentation depends on a number of dependencies to be built.
-If your docs don't have reproducible builds,
+If your docs don't have :term:`reproducible` builds,
 an update in a dependency can break your builds when least expected,
 or make your docs look different from your local version.
 This guide will help you to keep your builds working over time,
@@ -15,7 +15,6 @@ so that you can focus on content.
 Use a ``.readthedocs.yaml`` configuration file
 ----------------------------------------------
 
-
 We recommend using a :doc:`configuration file </config-file/v2>` to manage your documentation.
 Our config file *provides you per version settings*,
 and *those settings live in your Git repository*.
@@ -26,7 +25,7 @@ and ensures that all your versions can be rebuilt from a reproducible configurat
 Use a requirements file for Python dependencies
 -----------------------------------------------
 
-We recommend using a Pip :ref:`requirements file <pip:requirements-file-format>` or Conda :ref:`environment file <config-file/v2:conda.environment>` to pin Python dependencies.
+We recommend using a Pip :ref:`requirements file <pip:requirements-file-format>` or Conda :ref:`environment file <config-file/v2:conda.environment>` to :term:`pin <pinning>` Python dependencies.
 This ensures that top-level dependencies and extensions don't change.
 
 A configuration file with explicit dependencies looks like this:
@@ -66,7 +65,7 @@ A configuration file with explicit dependencies looks like this:
 Pin your transitive dependencies
 --------------------------------
 
-Once you have pinned your own dependencies,
+Once you have :term:`pinned <pinning>` your own dependencies,
 the next things to worry about are the dependencies of your dependencies.
 These are called *transitive dependencies*,
 and they can upgrade without warning if you do not pin these packages as well.
@@ -144,7 +143,7 @@ Check list ✅
 -------------
 
 If you followed this guide,
-you have pinned:
+you have:term:`pinned <pinning>`:
 
 * tool versions (Python, Node)
 * top-level dependencies (Sphinx, Sphinx extensions)

docs/user/tutorial/index.rst

@@ -79,7 +79,7 @@ On the authorization page, click the green :guilabel:`Authorize readthedocs` but
 
    Read the Docs needs elevated permissions to perform certain operations
    that ensure that the workflow is as smooth as possible,
-   like installing webhooks.
+   like installing :term:`webhooks <webhook>`.
    If you want to learn more,
    check out :ref:`connected-accounts:permissions for connected accounts`.