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

Author: humitos

.circleci/config.yml

@@ -9,6 +9,7 @@ jobs:
     docker:
       - image: 'cimg/python:3.10'
         environment:
+          # Don't skip search tests.
           TOX_POSARGS: ''
           PYTEST_COVERAGE: --cov-report=xml --cov-config .coveragerc --cov=. --cov-append
       - image: 'docker.elastic.co/elasticsearch/elasticsearch:8.10.2'
@@ -25,10 +26,33 @@ jobs:
       - run: git submodule update --init
       - run: sudo apt update
       - run: sudo apt install -y rclone
-      - run: pip install --user 'tox<5'
+      - run: pip install --user tox
       - run: tox -e py310
       - codecov/upload
 
+  tests-ext-theme:
+    docker:
+      - image: 'cimg/python:3.10'
+        environment:
+          # Don't skip search tests.
+          TOX_POSARGS: ''
+      - image: 'docker.elastic.co/elasticsearch/elasticsearch:8.10.2'
+        name: search
+        environment:
+          discovery.type: single-node
+          ES_JAVA_OPTS: -Xms750m -Xmx750m
+          ELASTIC_PASSWORD: password
+          # Disabled SSL for testing.
+          xpack.security.transport.ssl.enabled: 'false'
+    steps:
+      - checkout
+      - run: git submodule sync
+      - run: git submodule update --init
+      - run: sudo apt update
+      - run: sudo apt install -y rclone
+      - run: pip install --user tox
+      - run: tox -e ext-theme
+
   tests-embedapi:
     docker:
       - image: 'cimg/python:3.10'
@@ -75,6 +99,7 @@ workflows:
     jobs:
       - checks
       - tests
+      - tests-ext-theme
       - tests-embedapi:
           requires:
             - checks

CHANGELOG.rst

@@ -1,3 +1,59 @@
+Version 11.1.2
+--------------
+
+:Date: July 02, 2024
+
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11442 <https://github.com/readthedocs/readthedocs.org/pull/11442>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Run iri_to_uri on header values (`#11439 <https://github.com/readthedocs/readthedocs.org/pull/11439>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Release 11.1.1 (`#11438 <https://github.com/readthedocs/readthedocs.org/pull/11438>`__)
+* `@humitos <https://github.com/humitos>`__: Sales: send a Slack message to be able to contact the customer (`#11437 <https://github.com/readthedocs/readthedocs.org/pull/11437>`__)
+* `@humitos <https://github.com/humitos>`__: Organization: disable organization on non-active subscription (`#11430 <https://github.com/readthedocs/readthedocs.org/pull/11430>`__)
+* `@humitos <https://github.com/humitos>`__: Notification: update copy for "No HTML content found" (`#11410 <https://github.com/readthedocs/readthedocs.org/pull/11410>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: API: support rebuilding external version builds with build create endpoint (`#11407 <https://github.com/readthedocs/readthedocs.org/pull/11407>`__)
+* `@plaindocs <https://github.com/plaindocs>`__: Minor refactor of Private Python packages page (`#11395 <https://github.com/readthedocs/readthedocs.org/pull/11395>`__)
+* `@stsewd <https://github.com/stsewd>`__: Tests: run tests with the ext-theme (`#11383 <https://github.com/readthedocs/readthedocs.org/pull/11383>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add Pull Request builds page to settings (`#10656 <https://github.com/readthedocs/readthedocs.org/pull/10656>`__)
+
+Version 11.1.1
+--------------
+
+:Date: June 25, 2024
+
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11433 <https://github.com/readthedocs/readthedocs.org/pull/11433>`__)
+* `@humitos <https://github.com/humitos>`__: Requirements: upgrade `psycopg` to v3 (`#11432 <https://github.com/readthedocs/readthedocs.org/pull/11432>`__)
+* `@humitos <https://github.com/humitos>`__: Proxito: allow serving `zh` (deprecated) language code (`#11429 <https://github.com/readthedocs/readthedocs.org/pull/11429>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Be more defensive in redirect code (`#11427 <https://github.com/readthedocs/readthedocs.org/pull/11427>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Link website from docs sidebar (`#11426 <https://github.com/readthedocs/readthedocs.org/pull/11426>`__)
+* `@stsewd <https://github.com/stsewd>`__: Use literal `None` in session cookie samesite setting (`#11424 <https://github.com/readthedocs/readthedocs.org/pull/11424>`__)
+* `@humitos <https://github.com/humitos>`__: Release 11.1.0 (`#11423 <https://github.com/readthedocs/readthedocs.org/pull/11423>`__)
+* `@humitos <https://github.com/humitos>`__: Build: add support for Ubuntu 24.04 LTS (`#11421 <https://github.com/readthedocs/readthedocs.org/pull/11421>`__)
+* `@humitos <https://github.com/humitos>`__: Builds: don't call `git clean` anymore (`#11420 <https://github.com/readthedocs/readthedocs.org/pull/11420>`__)
+* `@humitos <https://github.com/humitos>`__: Ops: delete triggering a `time-test` build on `build-large` queue (`#11379 <https://github.com/readthedocs/readthedocs.org/pull/11379>`__)
+
+Version 11.1.0
+--------------
+
+:Date: June 18, 2024
+
+* `@olgaigig <https://github.com/olgaigig>`__: Update docs.rst (`#11422 <https://github.com/readthedocs/readthedocs.org/pull/11422>`__)
+* `@humitos <https://github.com/humitos>`__: Build: add support for Ubuntu 24.04 LTS (`#11421 <https://github.com/readthedocs/readthedocs.org/pull/11421>`__)
+* `@humitos <https://github.com/humitos>`__: Builds: don't call `git clean` anymore (`#11420 <https://github.com/readthedocs/readthedocs.org/pull/11420>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11415 <https://github.com/readthedocs/readthedocs.org/pull/11415>`__)
+* `@humitos <https://github.com/humitos>`__: New dashboard: use `app.` instead of `beta.` (`#11412 <https://github.com/readthedocs/readthedocs.org/pull/11412>`__)
+* `@humitos <https://github.com/humitos>`__: Build: remove "beta" from `build.commands` (`#11411 <https://github.com/readthedocs/readthedocs.org/pull/11411>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: update "Example projects" a little (`#11404 <https://github.com/readthedocs/readthedocs.org/pull/11404>`__)
+* `@stsewd <https://github.com/stsewd>`__: Oauth: Fix GitLab access token URL (`#11402 <https://github.com/readthedocs/readthedocs.org/pull/11402>`__)
+* `@humitos <https://github.com/humitos>`__: Build: update `asdf` and its plugins so we can build latest versions (`#11401 <https://github.com/readthedocs/readthedocs.org/pull/11401>`__)
+* `@humitos <https://github.com/humitos>`__: Settings: revert `USE_PROMOS` setting (`#11400 <https://github.com/readthedocs/readthedocs.org/pull/11400>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add Unknown for missing VCS class (`#11398 <https://github.com/readthedocs/readthedocs.org/pull/11398>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Release 11.0.0 (`#11397 <https://github.com/readthedocs/readthedocs.org/pull/11397>`__)
+* `@rffontenelle <https://github.com/rffontenelle>`__: GitHub with uppercase H in onboard_import.html (`#11396 <https://github.com/readthedocs/readthedocs.org/pull/11396>`__)
+* `@humitos <https://github.com/humitos>`__: Templates: pass `ADMIN_URL` into context (`#11394 <https://github.com/readthedocs/readthedocs.org/pull/11394>`__)
+* `@rffontenelle <https://github.com/rffontenelle>`__: Uppercase G for Gold membership in subscription_detail.html (`#11388 <https://github.com/readthedocs/readthedocs.org/pull/11388>`__)
+* `@humitos <https://github.com/humitos>`__: Build: update all `build.tools` and add latest versions (`#11386 <https://github.com/readthedocs/readthedocs.org/pull/11386>`__)
+* `@humitos <https://github.com/humitos>`__: Translations: disable `zh` code (`#11385 <https://github.com/readthedocs/readthedocs.org/pull/11385>`__)
+* `@humitos <https://github.com/humitos>`__: VCS: remove code for old VCS support (`#11377 <https://github.com/readthedocs/readthedocs.org/pull/11377>`__)
+
 Version 11.0.0
 --------------
 

common

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

docs/conf.py

@@ -6,34 +6,34 @@ the documentation for Read the Docs is built using Sphinx and hosted on Read the
 The docs are kept in the ``docs/`` directory at the top of the source tree,
 and are divided into developer and user-facing documentation.
 
-Contributing through the Github UI
+Contributing through the GitHub UI
 ----------------------------------
 
 If you're making small changes to the documentation,
-you can verify those changes through the documentation generated when you open a PR and can be accessed using the Github UI.
+you can verify those changes through the documentation generated when you open a PR and can be accessed using the GitHub UI.
 
-#. click the checkmark next to your commit and it will expand to have multiple options
+#. Click the checkmark next to your commit and it will expand to have multiple options.
 
-#. click the "details" link next to the "docs/readthedocs.org:docs" item
+#. Click the "details" link next to the "docs/readthedocs.org:docs" item:
 
    .. image:: /img/details_link.png
 
-#. navigate to the section of the documentation you worked on to verify your changes
+#. Navigate to the section of the documentation you worked on to verify your changes.
 
 Contributing from your local machine
 ------------------------------------
 
 If you're making large changes to the documentation,
 you may want to verify those changes locally before pushing upstream.
 
-#. clone the `readthedocs.org` repository:
+#. Clone the `readthedocs.org` repository:
 
    .. code-block:: console
 
       $ git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org/
 
-#. create a virtual environment with Python 3.8
-   (preferably the latest release, 3.8.12 at the time of writing),
+#. Create a virtual environment with Python 3.8
+   (preferably the latest release),
    activate it, and upgrade pip:
 
    .. code-block:: console
@@ -43,14 +43,14 @@ you may want to verify those changes locally before pushing upstream.
       $ source .venv/bin/activate
       (.venv) $ python -m pip install -U pip
 
-#. install documentation requirements
+#. Install the documentation requirements:
 
    .. code-block:: console
 
       (.venv) $ pip install -r requirements/testing.txt
       (.venv) $ pip install -r requirements/docs.txt
 
-#. build the documents
+#. Build the documents:
 
    To build the user-facing documentation:
 
@@ -66,4 +66,4 @@ you may want to verify those changes locally before pushing upstream.
       (.venv) $ cd docs
       (.venv) $ RTD_DOCSET=dev make livehtml
 
-#. the documents will be available at http://127.0.0.1:4444/ and will rebuild each time you edit and save a file.
+#. Check the changes locally at http://127.0.0.1:4444/ (rebuilds each time you edit and save a file).

docs/dev/docs.rst

@@ -49,6 +49,21 @@ Content
   * ``:guilabel:`<your username>` dropdown``
 * Make sure that **all bullet list items end with a period**, and don't mix periods with no periods.
 
+Linting
+~~~~~~~
+
+ReStructuredText for both the RTD user documentation and this developer documentation is linted with `pre-commit` for broken links,
+whitespace consistency, and other minor issues.
+
+You can fix many linting issues automatically by installing and running `pre-commit` locally.
+To run it on content you have have already committed, use the ``--from-ref`` and ``--to-ref`` `flags <https://pre-commit.com/#pre-commit-run>`__.
+
+.. code-block:: bash
+
+   pre-commit run --from-ref <OLDER_COMMIT> --to-ref <RECENT_COMMIT>
+
+Or use ``pre-commit run --all-files`` to lint all files.
+
 Word list
 ---------
 

docs/dev/style-guide.rst

@@ -130,6 +130,9 @@ Configuration of the Python environment to be used.
 python.install
 ``````````````
 
+Read the Docs uses :doc:`pip <pip:index>` by  default to install your Python packages, however if you are using a :ref:`Conda <config-file/v2:conda>` environment to manage your build, you'll need to use the Conda ``environment`` file instead.
+If you have a commercial plan you can also install :doc:`private dependencies </guides/private-python-packages>`.
+
 List of installation methods of packages and requirements.
 You can have several of the following methods.
 
@@ -158,16 +161,11 @@ Example:
        - requirements: docs/requirements.txt
        - requirements: requirements.txt
 
-.. warning::
-
-  If you are using a :ref:`Conda <config-file/v2:conda>` environment to
-  manage the build, this setting will not have any effect. Instead
-  add the extra requirements to the ``environment`` file of Conda.
-
 Packages
 ''''''''
 
-Install the project using ``pip install`` (recommended) or ``python setup.py install`` (deprecated).
+Install the project using ``pip install``.
+The use of ``python setup.py install`` is deprecated.
 
 The path to the package, relative to the root of the project.
 
@@ -186,15 +184,11 @@ The installation method.
 .. _Extra Requirements: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies
 .. _package dependencies: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#declaring-required-dependency
 
-.. warning::
-
-   You need to install your project with ``pip`` to use ``extra_requirements``.
-
 :Key: ``extra_requirements``
 :Type: ``list``
 :Default: ``[]``
 
-Example:
+For example, to run ``pip install .[docs]``:
 
 .. code-block:: yaml
 
@@ -207,12 +201,6 @@ Example:
          extra_requirements:
            - docs
 
-With the previous settings, Read the Docs will execute the next commands:
-
-.. prompt:: bash $
-
-   pip install .[docs]
-
 conda
 ~~~~~
 
@@ -274,7 +262,7 @@ Image names refer to the operating system Read the Docs uses to build them.
    Arbitrary Docker images are not supported.
 
 :Type: ``string``
-:Options: ``ubuntu-20.04``, ``ubuntu-22.04``, ``ubuntu-lts-latest``
+:Options: ``ubuntu-20.04``, ``ubuntu-22.04``, ``ubuntu-24.04``, ``ubuntu-lts-latest``
 :Required: ``true``
 
 .. note::