Merge branch 'main' of github.com:readthedocs/readthedocs.org into filesections

Author: ericholscher

.circleci/config.yml

@@ -81,7 +81,7 @@ jobs:
       - restore_cache:
           keys:
           - pre-commit-cache-{{ checksum "pre-commit-cache-key.txt" }}
-      - run: pip install --user 'tox<5'
+      - run: pip install --user tox
       - run: tox -e pre-commit
       - run: tox -e migrations
       - node/install:

CHANGELOG.rst

@@ -1,3 +1,45 @@
+Version 11.16.0
+---------------
+
+:Date: December 03, 2024
+
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11813 <https://github.com/readthedocs/readthedocs.org/pull/11813>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Add email for business projects and new dashboard change (`#11809 <https://github.com/readthedocs/readthedocs.org/pull/11809>`__)
+* `@humitos <https://github.com/humitos>`__: Development: try `uv` on Docker images (`#11807 <https://github.com/readthedocs/readthedocs.org/pull/11807>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Fix Sphinx tutorial seealso links (`#11806 <https://github.com/readthedocs/readthedocs.org/pull/11806>`__)
+* `@stsewd <https://github.com/stsewd>`__: Requirements: install unicode-slugify from pypi (`#11805 <https://github.com/readthedocs/readthedocs.org/pull/11805>`__)
+* `@humitos <https://github.com/humitos>`__: Django Debug Toolbar: disable slow panels (`#11804 <https://github.com/readthedocs/readthedocs.org/pull/11804>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Upgrade NR to fix issue (`#11802 <https://github.com/readthedocs/readthedocs.org/pull/11802>`__)
+* `@humitos <https://github.com/humitos>`__: Release 11.15.0 (`#11800 <https://github.com/readthedocs/readthedocs.org/pull/11800>`__)
+* `@humitos <https://github.com/humitos>`__: Addons: create `AddonsConfig` on `Project.post_save` (`#11799 <https://github.com/readthedocs/readthedocs.org/pull/11799>`__)
+* `@stsewd <https://github.com/stsewd>`__: Allauth: disable account enumeration protection (`#11797 <https://github.com/readthedocs/readthedocs.org/pull/11797>`__)
+* `@humitos <https://github.com/humitos>`__: Addons: base version to compare against (DocDiff and File Tree Diff) (`#11794 <https://github.com/readthedocs/readthedocs.org/pull/11794>`__)
+* `@humitos <https://github.com/humitos>`__: File tree diff: migrate feature flag to model field (`#11793 <https://github.com/readthedocs/readthedocs.org/pull/11793>`__)
+* `@plaindocs <https://github.com/plaindocs>`__: Docusaurus basics (`#11752 <https://github.com/readthedocs/readthedocs.org/pull/11752>`__)
+
+Version 11.15.0
+---------------
+
+:Date: November 26, 2024
+
+* `@stsewd <https://github.com/stsewd>`__: Allauth: disable account enumeration protection (`#11797 <https://github.com/readthedocs/readthedocs.org/pull/11797>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11792 <https://github.com/readthedocs/readthedocs.org/pull/11792>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Support RTD_USE_PROMOS for setting USE_PROMOS in dev (`#11790 <https://github.com/readthedocs/readthedocs.org/pull/11790>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Increase default docker limits (`#11788 <https://github.com/readthedocs/readthedocs.org/pull/11788>`__)
+* `@stsewd <https://github.com/stsewd>`__: Set brownouts for deprecated embed API v2 (`#11786 <https://github.com/readthedocs/readthedocs.org/pull/11786>`__)
+* `@humitos <https://github.com/humitos>`__: Use addons JavaScript file from Docker container (`#11785 <https://github.com/readthedocs/readthedocs.org/pull/11785>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add Markdoc to the doc tools (`#11782 <https://github.com/readthedocs/readthedocs.org/pull/11782>`__)
+* `@humitos <https://github.com/humitos>`__: Migrations: re-order them for deploy (`#11779 <https://github.com/readthedocs/readthedocs.org/pull/11779>`__)
+* `@humitos <https://github.com/humitos>`__: Release 11.14.0 (`#11778 <https://github.com/readthedocs/readthedocs.org/pull/11778>`__)
+* `@stsewd <https://github.com/stsewd>`__: Docs: update connected accounts steps to use env vars (`#11777 <https://github.com/readthedocs/readthedocs.org/pull/11777>`__)
+* `@humitos <https://github.com/humitos>`__: Addons: make default root CSS selector a shared option (`#11767 <https://github.com/readthedocs/readthedocs.org/pull/11767>`__)
+* `@humitos <https://github.com/humitos>`__: Addons: `load_when_embedded` config (`#11765 <https://github.com/readthedocs/readthedocs.org/pull/11765>`__)
+* `@stsewd <https://github.com/stsewd>`__: Custom domain: check CNAME when adding domains (`#11747 <https://github.com/readthedocs/readthedocs.org/pull/11747>`__)
+* `@stsewd <https://github.com/stsewd>`__: Docs: update custom domains docs (`#11734 <https://github.com/readthedocs/readthedocs.org/pull/11734>`__)
+* `@stsewd <https://github.com/stsewd>`__: Build: allow partial override of build steps (`#11710 <https://github.com/readthedocs/readthedocs.org/pull/11710>`__)
+* `@humitos <https://github.com/humitos>`__: Dependencies: use GitHub Action + pip-tools (`#9479 <https://github.com/readthedocs/readthedocs.org/pull/9479>`__)
+* `@humitos <https://github.com/humitos>`__: GitHub Action: add link to Pull Request preview (`#9450 <https://github.com/readthedocs/readthedocs.org/pull/9450>`__)
+
 Version 11.14.0
 ---------------
 

dockerfiles/Dockerfile

@@ -56,26 +56,26 @@ RUN npm install -g nodemon
 RUN sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && \
     locale-gen
 
-RUN pip3 install --no-cache-dir --upgrade pip
+# Install ``uv`` package manager
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/bin/" sh
 
 # Ensure that ``python`` is in the PATH so that ``./manage.py`` works
 RUN ln -s /usr/bin/python3 /usr/bin/python
 
 WORKDIR /tmp
 
-COPY requirements/pip.txt pip.txt
 COPY requirements/docker.txt docker.txt
-RUN pip3 install --no-cache-dir -r docker.txt
+RUN uv pip sync --system docker.txt
 
 # Install readthedocs-ext only if GITHUB_TOKEN is provided
 WORKDIR /usr/src/app/checkouts/
 RUN if [ -n "$GITHUB_TOKEN" ] ; \
         then \
         git clone --depth 1 https://${GITHUB_USER}:${GITHUB_TOKEN}@github.com/readthedocs/readthedocs-ext ; \
-        pip3 install --no-cache-dir -e readthedocs-ext ; \
+        uv pip install --system --no-cache-dir -e readthedocs-ext ; \
         fi
 
 RUN git clone --depth 1 https://github.com/readthedocs/ext-theme ; \
-    pip3 install --no-cache-dir -e ext-theme
+    uv pip install --system --no-cache-dir -e ext-theme
 
 WORKDIR /usr/src/app/checkouts/readthedocs.org

docs/conf.py

@@ -80,7 +80,7 @@
 
 master_doc = "index"
 copyright = "Read the Docs, Inc & contributors"
-version = "11.14.0"
+version = "11.16.0"
 release = version
 exclude_patterns = ["_build", "shared", "_includes"]
 default_role = "obj"

docs/dev/settings.rst

@@ -168,3 +168,10 @@ The following secrets are required to use ``djstripe`` and our Stripe integratio
 .. envvar:: RTD_STRIPE_SECRET
 .. envvar:: RTD_STRIPE_PUBLISHABLE
 .. envvar:: RTD_DJSTRIPE_WEBHOOK_SECRET
+
+Ethical Ads variables
+~~~~~~~~~~~~~~~~~~~~~
+
+The following variables are required to use ``ethicalads`` in dev:
+
+.. envvar:: RTD_USE_PROMOS

docs/user/api/v3.rst

@@ -2001,10 +2001,11 @@ Embed
     :query string url: full URL of the document (with optional fragment) to fetch content from.
     :query string doctool: *optional* documentation tool key name used to generate the target documentation (currently, only ``sphinx`` is accepted)
     :query string doctoolversion: *optional* documentation tool version used to generate the target documentation (e.g. ``4.2.0``).
+    :query string maincontent: *optional* CSS selector for the main content of the page (e.g. ``div#main``).
 
     .. note::
 
-       Passing ``?doctool=`` and ``?doctoolversion=`` may improve the response,
+       Passing ``?doctool=``, ``?doctoolversion=`` and ``?maincontent=`` may improve the response
        since the endpoint will know more about the exact structure of the HTML and can make better decisions.
 
 Additional APIs

docs/user/guides/embedding-content.rst

@@ -63,6 +63,7 @@ from our own docs and will populate the content of it into the ``#help-container
       'url': 'https://docs.readthedocs.io/en/latest/automation-rules.html%23creating-an-automation-rule',
       // 'doctool': 'sphinx',
       // 'doctoolversion': '4.2.0',
+      // 'maincontent': 'div#main',
     };
     var url = 'https://readthedocs.org/api/v3/embed/?' + $.param(params);
     $.get(url, function(data) {

docs/user/index.rst

@@ -10,6 +10,8 @@ Read the Docs: documentation simplified
    /intro/doctools
    /intro/mkdocs
    /intro/sphinx
+   /intro/docusaurus
+   /intro/markdoc
    /intro/add-project
    /examples
 

docs/user/intro/doctools.rst

@@ -29,3 +29,23 @@ with more coming soon.
              :bdg-success:`rst` :bdg-success:`md`
         Written in
              :bdg-info:`python`
+
+    .. grid-item-card::  Docusarus
+        :link: docusaurus.html
+
+        Docusaurus is a static-site generator that builds a single-page application with fast client-side navigation and out-of-the-box documentation features.
+
+        Supported formats
+             :bdg-success:`mdx` :bdg-success:`md`
+        Written in
+             :bdg-info:`React`
+
+    .. grid-item-card::  Markdoc
+        :link: markdoc.html
+
+        Markdoc is a documentation tool developed by Stripe that allows you to write documentation in a custom Markdown flavor.
+
+        Supported formats
+             :bdg-success:`md`
+        Written in
+             :bdg-info:`javascript`

docs/user/intro/docusaurus.rst

@@ -0,0 +1,93 @@
+
+Docusarus
+=========
+
+.. meta::
+   :description lang=en: Hosting Docusaurus sites on Read the Docs.
+
+`Docusaurus`_ is a static-site generator that builds a single-page application with fast client-side navigation and out-of-the-box documentation features.
+
+Minimal configuration required to build a Docusaurus project on Read the Docs looks like this,
+specifying a nodejs toolchain on Ubuntu, using multiple :ref:`build <config-file/v2:build>` commands to install the requirements,
+build the site, and copy the output to $READTHEDOCS_OUTPUT:
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+    version: 2
+    build:
+    os: "ubuntu-22.04"
+    tools:
+        nodejs: "18"
+    commands:
+        # "docs/" was created following the Docusaurus tutorial:
+        # npx create-docusaurus@latest docs classic
+        # but you can just use your existing Docusaurus site
+        #
+        # Install Docusaurus dependencies
+        - cd docs/ && npm install
+        # Build the site
+        - cd docs/ && npm run build
+        # Copy generated files into Read the Docs directory
+        - mkdir --parents $READTHEDOCS_OUTPUT/html/
+        - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/
+
+.. _Docusaurus: https://docusaurus.io/
+
+Limitations
+-----------
+
+.. csv-table:: Limitations
+   :header: "Feature", "Description", "Supported"
+
+   "Search", "Provides full-text search capabilities.", "Not supported"
+   "Files changed", "Ability to see what HTML files changes in pull request previews", "Not supported"
+
+
+Quick start
+-----------
+
+- If you have an existing Docusaurus project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
+
+- If you're new to Docusaurus, check out the official `Fast Track`_ guide.
+
+.. _Fast Track: https://docusaurus.io/docs#fast-track
+
+Configuring Docusaurus and Read the Docs addons
+-----------------------------------------------
+
+For optimal integration with Read the Docs, make the optional following configuration changes to your Docusaurus config.
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: none
+
+Set the canonical URL
+~~~~~~~~~~~~~~~~~~~~~
+
+A :doc:`canonical URL </canonical-urls>` allows you to specify the preferred version of a web page
+to prevent duplicated content.
+
+Set your Docusaurus `url`_  to your Read the Docs canonical URL using `dotenv <https://www.npmjs.com/package/dotenv>`__ and a
+:doc:`Read the Docs environment variable </reference/environment-variables>`:
+
+.. code-block:: js
+    :caption: docusaurus.config.js
+
+    import 'dotenv/config';
+
+    export default {
+        url: process.env.READTHEDOCS_CANONICAL_URL,
+    };
+
+.. _url: https://docusaurus.io/docs/configuration#syntax-to-declare-docusaurus-config
+
+Example repository and demo
+---------------------------
+
+Example repository
+    https://github.com/readthedocs/test-builds/tree/docusaurus
+
+Demo
+    https://test-builds.readthedocs.io/en/docusaurus/

docs/user/intro/markdoc.rst

@@ -0,0 +1,90 @@
+Markdoc
+=======
+
+.. meta::
+   :description lang=en: Hosting Markdoc documentation on Read the Docs.
+
+`Markdoc`_ is a powerful documentation framework that allows you to write documentation in a flavor of Markdown.
+
+Minimal configuration is required to build an existing Markdoc project on Read the Docs.
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+    version: 2
+
+    build:
+        os: ubuntu-24.04
+        tools:
+            nodejs: "22"
+        commands:
+            # Install dependencies
+            - cd docs/ && npm install
+            # Build the site
+            - cd docs/ && npm run build
+            # Copy generated files into Read the Docs directory
+            - mkdir --parents $READTHEDOCS_OUTPUT/html/
+            - cp --verbose --recursive docs/out/* $READTHEDOCS_OUTPUT/html/
+
+.. _Markdoc: https://markdoc.io/
+
+Example configuration
+---------------------
+
+In order to build a Markdoc project on Read the Docs,
+you need to generate static HTML from the Next JS build:
+
+.. code-block:: js
+   :caption: next.config.js
+
+    const withMarkdoc = require('@markdoc/next.js');
+
+    const nextConfig = {
+        // Optional: Export HTML files instead of a Node.js server
+        output: 'export',
+
+        // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
+        trailingSlash: true,
+
+        // Use Canonical URL, but only the path and with no trailing /
+        // End result is like: `/en/latest`
+        basePath: process.env.READTHEDOCS_CANONICAL_URL
+          ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, "")
+          : "",
+    }
+
+    module.exports =
+        withMarkdoc({mode: 'static'})({
+            pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdoc'],
+            ...nextConfig,
+    });
+
+Limitations
+-----------
+
+All Read the Docs features are supported for Markdoc projects.
+There may be some Markdoc features that depend on server-side rendering that are not supported.
+
+Getting started
+---------------
+
+- If you have an existing Markdoc project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
+- If you're new to Markdoc, check out the official `Getting started with Markdoc`_ guide.
+
+.. _Getting started with Markdoc: https://markdoc.io/docs/getting-started
+
+Example repository and demo
+---------------------------
+
+Example repository
+    https://github.com/readthedocs/test-builds/tree/markdoc
+
+Demo
+    https://test-builds.readthedocs.io/en/markdoc/
+
+Further reading
+---------------
+
+* `Markdoc documentation`_
+
+.. _Markdoc documentation: https://markdoc.io/docs

docs/user/intro/sphinx.rst

@@ -133,9 +133,7 @@ You can now continue writing your docs in ``.md`` files and it will work with Sp
 .. seealso::
 
    `Getting started with MyST in Sphinx <https://myst-parser.readthedocs.io/en/latest/sphinx/intro.html>`_
-
-   :doc:`/guides/migrate-rest-myst`
-     Learn how to use references between different Sphinx projects, for instance between subprojects
+     Learn how to use MyST to write Markdown documentation in your Sphinx project.
 
    :doc:`/guides/migrate-rest-myst`
      Start writing Markdown in your existing reStructuredText project, or migrate it completely.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "readthedocs",
-  "version": "11.14.0",
+  "version": "11.16.0",
   "description": "Read the Docs build dependencies",
   "author": "Read the Docs, Inc <[email protected]>",
   "scripts": {

readthedocs/__init__.py

@@ -1,4 +1,4 @@
 """Read the Docs."""
 
 
-__version__ = "11.14.0"
+__version__ = "11.16.0"