Merge branch 'main' of github.com:readthedocs/readthedocs.org into humitos/allow-any-filename-pdf-epub

Author: humitos

.readthedocs.yml

@@ -6,7 +6,9 @@ formats:
 
 sphinx:
   configuration: docs/conf.py
-  fail_on_warning: true
+
+  # Disabled due to temporary issue with Django docs
+  fail_on_warning: false
 
 python:
   install:
@@ -31,6 +33,12 @@ build:
           exit 183;
         fi
 
+    # Install our Sphinx Theme version that uses the Addons CustomEvent to generate the integrated flyout
+    # TODO: this custom installation once a new release has been done
+    post_install:
+      - pip uninstall --yes sphinx-rtd-theme
+      - pip install git+https://github.com/readthedocs/sphinx_rtd_theme.git@humitos/addons-flyout#egg=sphinx-rtd-theme
+
 search:
   ranking:
     # Deprecated content

CHANGELOG.rst

@@ -6,54 +6,52 @@ Welcome to Read the Docs
 Purpose
 -------
 
-`Read the Docs`_ hosts documentation for the open source community. It supports
-Sphinx_ docs written with reStructuredText_, and can pull from your Subversion_,
-Bazaar_, Git_, and Mercurial_ repositories.
+`Read the Docs`_ hosts documentation for the open source community.
+It supports many documentation tools
+(e.g. Sphinx_ docs written with reStructuredText_, MkDocs_ docs written with markdown_, among others),
+and can pull Git_ repositories.
 Then we build documentation and host it for you.
-Think of it as *Continuous Documentation*.
+Think of it as *Continuous Documentation*, or Docs as Code.
 
 .. _Read the docs: https://readthedocs.org/
 .. _Sphinx: http://www.sphinx-doc.org/
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _Subversion: http://subversion.tigris.org/
-.. _Bazaar: http://bazaar.canonical.com/
 .. _Git: http://git-scm.com/
-.. _Mercurial: https://www.mercurial-scm.org/
+.. _MkDocs: https://www.mkdocs.org/
+.. _markdown: https://daringfireball.net/projects/markdown/
 
-Documentation for RTD
----------------------
+Documentation for Read the Docs
+-------------------------------
 
-You will find complete documentation for setting up your project at `the Read
-the Docs site`_.
+You will find complete documentation for setting up your project at `the Read the Docs site`_.
 
 .. _the Read the Docs site: https://docs.readthedocs.io/
 
 Get in touch
 ------------
 
-You can find information about getting in touch with Read the Docs at our `Contribution page <https://docs.readthedocs.io/en/latest/contribute.html#get-in-touch>`_.
+You can find information about getting in touch with Read the Docs at our
+`Contribution page <https://docs.readthedocs.io/en/latest/contribute.html#get-in-touch>`_.
 
 Contributing
 ------------
 
-You can find information about contributing to Read the Docs at our `Contribution page <https://docs.readthedocs.io/en/latest/contribute.html>`_.
+You can find information about contributing to Read the Docs at our
+`Contribution page <https://docs.readthedocs.io/en/latest/contribute.html>`_.
 
 Quickstart for GitHub hosted projects
 -------------------------------------
 
-By the end of this quickstart, you will have a new project automatically updated
-when you push to GitHub.
+By the end of this quickstart, you will have a new project automatically updated when you push to GitHub.
 
-#. Create an account on `Read the Docs`_.  You will get an email verifying your
-   email address which you should accept within 7 days.
-
-#. Log in and click on "Import a Project".
-
-#. Click "Connect to GitHub" in order to connect your account's repositories to GitHub.
+#. Create an account on `Read the Docs`_ by signing up with GitHub.
 
 #. When prompted on GitHub, give access to your account.
 
-#. Click "Import a Repository" and select any desired repository.
+#. Log in and click on "Add project".
+
+#. Start typing the name of your repository and select it from the list,
+   and click "Continue".
 
 #. Change any information if desired and click "Next".
 

README.rst

@@ -10,8 +10,6 @@
 # instead we need to hit NGINX's IP (this is used on Embed API from
 # -ext for example) Setting a static IP for NGINX, allow us to
 # override /etc/hosts with this IP.
-version: '3'
-
 networks:
   readthedocs:
     driver: bridge

common

@@ -33,6 +33,16 @@ RUN apt-get -y install \
         npm \
         rclone
 
+# Dependencies for django-allauth SAML support.
+# See:
+# - https://github.com/SAML-Toolkits/python3-saml#installation
+# - https://github.com/xmlsec/python-xmlsec#linux-debian
+RUN apt-get -y install \
+      pkg-config \
+      libxml2-dev \
+      libxmlsec1-dev \
+      libxmlsec1-openssl
+
 # Gets the MinIO mc client used to add buckets upon initialization
 # If this client should have issues running inside this image, it is also
 # fine to defer it to a separate image.

docker-compose.override.yml

@@ -1,5 +1,3 @@
-version: '3'
-
 services:
   assets:
     image: node:8.16

dockerfiles/Dockerfile

@@ -132,7 +132,6 @@ server {
         proxy_set_header Host $http_host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Host $host;
         add_header X-Served Proxito-404-Fallback always;
     }
 

dockerfiles/docker-compose-assets.yml

@@ -7,9 +7,3 @@
   <script defer data-domain="{{ plausible_domain }}" src="https://plausible.io/js/script.js"></script>
   {% endif %}
 {% endblock extrahead %}
-
-{% block document %}
-  {{ super() }}
-
-  {% include "ethicalads.html" %}
-{% endblock document %}

dockerfiles/nginx/proxito.conf.template

@@ -24,7 +24,6 @@
     "notfound.extension",
     "sphinx_copybutton",
     "sphinx_design",
-    "sphinx_search.extension",
     "sphinx_tabs.tabs",
     "sphinx-prompt",
     "sphinx.ext.autodoc",
@@ -77,7 +76,7 @@
 
 master_doc = "index"
 copyright = "Read the Docs, Inc & contributors"
-version = "10.21.0"
+version = "11.0.0"
 release = version
 exclude_patterns = ["_build", "shared", "_includes"]
 default_role = "obj"
@@ -160,9 +159,6 @@
 html_css_files = ["css/custom.css", "css/sphinx_prompt_css.css"]
 html_js_files = ["js/expand_tabs.js"]
 
-if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
-    html_js_files.append("js/readthedocs-doc-diff.js")
-
 html_logo = "img/logo.svg"
 html_theme_options = {
     "logo_only": True,

docs/_static/js/readthedocs-doc-diff.js

@@ -258,7 +258,10 @@ Project details
             "translation_of": null,
             "urls": {
                 "documentation": "http://pip.pypa.io/en/stable/",
-                "home": "https://pip.pypa.io/"
+                "home": "https://readthedocs.org/projects/pip/",
+                "downloads": "https://readthedocs.org/projects/pip/downloads/",
+                "builds": "https://readthedocs.org/projects/pip/builds/",
+                "versions": "https://readthedocs.org/projects/pip/versions/",
             },
             "tags": [
                 "distutils",
@@ -556,6 +559,7 @@ Version detail
             "ref": "19.0.2",
             "built": true,
             "active": true,
+            "aliases": ["VERSION"],
             "hidden": false,
             "type": "tag",
             "last_build": "{BUILD}",

docs/_templates/ethicalads.html

@@ -356,6 +356,33 @@ Take a look at the following example:
      configuration: docs/conf.py
 
 
+Install dependencies with ``uv``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Projects can use `uv <https://github.com/astral-sh/uv/>`__,
+to install Python dependencies, usually reducing the time taken to install compared to pip.
+Take a look at the following example:
+
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+   version: 2
+
+   build:
+     os: "ubuntu-22.04"
+     tools:
+       python: "3.10"
+     commands:
+       - asdf plugin add uv
+       - asdf install uv latest
+       - asdf global uv latest
+       - uv venv
+       - uv pip install .[docs]
+       - .venv/bin/python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html
+
+You can use ``-r docs/requirements.txt``, etc. instead as needed. MkDocs projects could use ``NO_COLOR=1 .venv/bin/mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html`` instead.
+
 Update Conda version
 ^^^^^^^^^^^^^^^^^^^^
 

docs/_templates/layout.html

@@ -44,6 +44,21 @@ permissions are managed by the :ref:`internal Read the Docs's teams <commercial/
 This feature is only available on the **Pro plan** and above.
 Learn how to configure this SSO method with our :doc:`/guides/setup-single-sign-on-google-email`.
 
+SSO with SAML
+-------------
+
+.. note::
+
+   This feature is in beta, and will be available for **Enterprise** plans only.
+   Contact :doc:`support </support>` to enable this feature for your organization.
+
+   **At the moment only Okta is supported as a SAML identity provider.**
+
+This feature allows you to easily manage access to users that are part of your identity provider.
+As SAML doesn't provide information about which projects a user has access to,
+permissions are managed by the :ref:`internal Read the Docs's teams <commercial/organizations:Team Types>` authorization system.
+Learn how to configure this SSO method with our :doc:`guide </guides/set-up-single-sign-on-saml>`.
+
 Requesting additional providers
 -------------------------------
 

docs/conf.py

@@ -42,8 +42,8 @@ Billing information
 
 We provide both monthly and annual subscriptions for all plans.
 Annual plans are given a 2 month discount compared to monthly billing.
-We only support credit card billing for our Basic and Advanced plans.
-For our Pro and Enterprise users, we support invoice-based and PO billing.
+We support credit card billing for all plans.
+Pro and Enterprise plans can use invoice-based and PO billing for annual subscriptions.
 
 .. tip::
     We recommend paying by credit card for all users,

docs/user/api/v3.rst

@@ -128,7 +128,7 @@ you should define the Python version in ``build.tools.python``.
 The ``python`` key contains a list of sub-keys,
 specifying the requirements to install.
 
-- Use ``python.install.package`` to install the project itself as a Python package using pip
+- Use ``python.install.path`` to install the project itself as a Python package using pip
 - Use ``python.install.requirements`` to install packages from a requirements file
 - Use ``build.jobs`` to install packages using Poetry or PDM
 

docs/user/build-customization.rst

@@ -330,9 +330,11 @@ You can use several interpreters and versions, from CPython, Miniconda, and Mamb
   - ``3.12``
   - ``latest`` (alias for the latest version available on Read the Docs)
   - ``miniconda3-4.7``
+  - ``miniconda3-3.12-24.1``
   - ``miniconda-latest`` (alias for the latest version available on Read the Docs)
   - ``mambaforge-4.10``
   - ``mambaforge-22.9``
+  - ``mambaforge-23.11``
   - ``mambaforge-latest`` (alias for the latest version available on Read the Docs)
 
 build.tools.nodejs
@@ -371,6 +373,7 @@ Rust version to use.
    - ``1.64``
    - ``1.70``
    - ``1.75``
+   - ``1.78``
    - ``latest`` (alias for the latest version available on Read the Docs)
 
 build.tools.golang
@@ -385,6 +388,7 @@ Go version to use.
    - ``1.19``
    - ``1.20``
    - ``1.21``
+   - ``1.22``
    - ``latest`` (alias for the latest version available on Read the Docs)
 
 build.apt_packages