Merge tag '9.10.0' into rel

Author: humitos

.circleci/config.yml

@@ -2,6 +2,7 @@ version: 2.1
 
 orbs:
   codecov: codecov/[email protected]
+  node: circleci/[email protected]
 
 jobs:
   tests:
@@ -37,21 +38,16 @@ jobs:
   checks:
     docker:
       - image: 'cimg/python:3.10'
-        environment:
-          NODE_VERSION: 10.17.0
     steps:
       - checkout
       - run: git submodule sync
       - run: git submodule update --init
       - run: pip install --user 'tox<5'
       - run: tox -e pre-commit
       - run: tox -e migrations
-      - run: scripts/circle/install_node.sh
-      - run:
-          name: Add node to the path
-          command: |
-            echo 'export PATH=~/.nvm/versions/node/v${NODE_VERSION}/bin:$PATH' >> $BASH_ENV
-            source $BASH_ENV
+      - node/install:
+          node-version: '10.17.0'
+      - run: npm ci
       - run: tox -e eslint
 
 workflows:

CHANGELOG.rst

@@ -1,3 +1,27 @@
+Version 9.10.0
+--------------
+
+:Date: March 28, 2023
+
+* `@stsewd <https://github.com/stsewd>`__: Docs: test new search extension release (`#10197 <https://github.com/readthedocs/readthedocs.org/pull/10197>`__)
+* `@humitos <https://github.com/humitos>`__: Javascript client: search-as-you-type API response (`#10196 <https://github.com/readthedocs/readthedocs.org/pull/10196>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#10192 <https://github.com/readthedocs/readthedocs.org/pull/10192>`__)
+* `@agjohnson <https://github.com/agjohnson>`__:  Filters: several bug fixes and some filter tuning (`#10191 <https://github.com/readthedocs/readthedocs.org/pull/10191>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Make our homepage conditional on the new dashboard (`#10189 <https://github.com/readthedocs/readthedocs.org/pull/10189>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Docs: Changes to main index page (Diátaxis) (`#10186 <https://github.com/readthedocs/readthedocs.org/pull/10186>`__)
+* `@stsewd <https://github.com/stsewd>`__: Proxito: allow serving files under the projects dir (`#10180 <https://github.com/readthedocs/readthedocs.org/pull/10180>`__)
+* `@stsewd <https://github.com/stsewd>`__: Redirects: test redirects with projects prefix (`#10179 <https://github.com/readthedocs/readthedocs.org/pull/10179>`__)
+* `@stsewd <https://github.com/stsewd>`__: Proxito: refactor project download view (`#10178 <https://github.com/readthedocs/readthedocs.org/pull/10178>`__)
+* `@stsewd <https://github.com/stsewd>`__: Update common (`#10177 <https://github.com/readthedocs/readthedocs.org/pull/10177>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Docs: Removal of implicit Intersphinx reference labels to MyST-based documentation (`#10176 <https://github.com/readthedocs/readthedocs.org/pull/10176>`__)
+* `@stsewd <https://github.com/stsewd>`__: Build: fix API call to version.patch() (`#10175 <https://github.com/readthedocs/readthedocs.org/pull/10175>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Replace nvm/asdf with native CircleCI node installation (`#10174 <https://github.com/readthedocs/readthedocs.org/pull/10174>`__)
+* `@humitos <https://github.com/humitos>`__: Build: hardcode the Docker username for now (`#10172 <https://github.com/readthedocs/readthedocs.org/pull/10172>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Release 9.9.1 (`#10169 <https://github.com/readthedocs/readthedocs.org/pull/10169>`__)
+* `@humitos <https://github.com/humitos>`__: Build: expose VCS-related environment variables (`#10168 <https://github.com/readthedocs/readthedocs.org/pull/10168>`__)
+* `@humitos <https://github.com/humitos>`__: Build: export READTHEDOCS_CANONICAL_URL variable (`#10166 <https://github.com/readthedocs/readthedocs.org/pull/10166>`__)
+* `@humitos <https://github.com/humitos>`__: Project: only support Git as VCS for new projects (`#10114 <https://github.com/readthedocs/readthedocs.org/pull/10114>`__)
+
 Version 9.9.1
 -------------
 

common

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

docs/conf.py

@@ -34,7 +34,7 @@ The canonical URL takes the following into account:
 
 * The default version of your project (usually "latest" or "stable").
 * The canonical :doc:`custom domain </custom-domains>` if you have one,
-  otherwise the default :ref:`subdomain <default_subdomain>` will be used.
+  otherwise the default :ref:`subdomain <default-subdomain>` will be used.
 
 For example, if you have a project named ``example-docs``
 with a custom domain ``https://docs.example.com``,

docs/user/canonical-urls.rst

@@ -5,7 +5,7 @@ You can serve your documentation project from your own domain,
 for instance ``docs.example.com``.
 This is great for maintaining a consistent brand for your product and its documentation.
 
-.. _default_subdomain:
+.. _default-subdomain:
 
 .. rubric:: Default subdomains
 

docs/user/custom-domains.rst

@@ -39,10 +39,10 @@ Real-life examples
 
 .. image:: _static/images/awesome-list.svg
   :alt: Awesome List badge
-  :target: https://github.com/readthedocs-examples/
+  :target: https://github.com/readthedocs-examples/awesome-read-the-docs
 
 We maintain an **Awesome List** where you can contribute new shiny examples of using Read the Docs.
-Please refer to the instructions on how to submit new entries on `Awesome Read the Docs Projects <https://github.com/readthedocs-examples/>`_.
+Please refer to the instructions on how to submit new entries on `Awesome Read the Docs Projects <https://github.com/readthedocs-examples/awesome-read-the-docs>`__.
 
 
 Contributing an example project

docs/user/examples.rst

@@ -1,5 +1,5 @@
-Cross-referencing with Sphinx
-=============================
+How to use cross-references with Sphinx
+=======================================
 
 When writing documentation you often need to link to other pages of your documentation,
 other sections of the current page, or sections from other pages.

docs/user/guides/cross-referencing-with-sphinx.rst

@@ -10,3 +10,8 @@ and how to write successful documentation.
 .. tip::
    We recommend looking through the list,
    maybe there is a guide you hadn't looked for?
+
+.. toctree::
+   :glob:
+
+   */index

docs/user/guides/index.rst

@@ -114,8 +114,8 @@ Each editor has a different way of doing it:
 
 - The classical Jupyter Notebook interface
   provides a "Save Notebook Widget State" action in the "Widgets" menu,
-  :ref:`as explained in the ipywidgets
-  documentation <ipywidgets:/embedding.md#embedding-widgets-in-html-web-pages>`.
+  :doc:`as explained in the ipywidgets
+  documentation <ipywidgets:embedding>`.
   You need to click it before exporting your notebook to HTML.
 - JupyterLab provides a "Save Widget State Automatically" option in the "Settings" menu.
   You need to leave it checked so that widget state is automatically saved.
@@ -131,7 +131,7 @@ Each editor has a different way of doing it:
    JupyterLab option to save the interactive widget state automatically
 
 For example, if you create a notebook with a simple
-:ref:`ipywidgets:/examples/widget list.ipynb#intslider`
+`IntSlider <https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20List.html#intslider>`__
 widget from ipywidgets and save the widget state,
 the slider will render correctly in Sphinx.
 

docs/user/guides/jupyter.rst

@@ -62,156 +62,115 @@ Read the Docs: documentation simplified
 
    <a style="display: none;" rel="me" href="https://fosstodon.org/@readthedocs">Mastodon</a>
 
-`Read the Docs`_ simplifies software documentation
+Read the Docs simplifies software documentation
 by building, versioning, and hosting of your docs, automatically.
-This enables many "docs like code" workflows,
-keeping your code & documentation as close as possible.
+Treating documentation like code keeps your team in the same tools,
+and your documentation up to date.
 
-Never out of sync |:arrows_counterclockwise:|
-    Whenever you push code to your favorite version control system,
-    whether that is Git or Mercurial,
+|:arrows_counterclockwise:| Up to date documentation
+    Whenever you push code to Git,
     Read the Docs will automatically build your docs
     so your code and documentation are always up-to-date.
-    Read more about :doc:`/integrations`.
+    Get started with our :doc:`tutorial </tutorial/index>`.
 
-Multiple versions |:card_index_dividers:|
-    Read the Docs can host and build multiple versions of your docs
-    so having a 1.0 version of your docs and a 2.0 version
-    of your docs is as easy as having a separate branch or tag in your version control system.
-    Read more about :doc:`/versions`.
+|:card_index_dividers:| Documentation for every version
+    Read the Docs can host multiple versions of your docs.
+    Keep your 1.0 and 2.0 documentation online,
+    pulled directly from Git.
+    Start hosting all your :doc:`versions </versions>`.
 
-Open Source and User Focused |:heartbeat:|
-    Our code is free and `open source <https://github.com/readthedocs/>`_.
-    :doc:`Our company </about/index>` is bootstrapped and 100% user focused.
+|:heartbeat:| Open source and user focused
+    Our company is bootstrapped and 100% user-focused,
+    so our product gets better for our users instead of our investors.
     |org_brand| hosts documentation for over 100,000 large
-    and small open source projects,
-    in almost every human and computer language.
+    and small open source projects.
     |com_brand| supports hundreds of organizations with product and internal documentation.
+    Learn more about :doc:`our two platforms </choosing-a-site>`.
 
-.. _Read the docs: https://readthedocs.org/
+First time here?
+----------------
 
-You can find out more about our all the :doc:`features </reference/features>` in these pages.
+We have a few places for you to get started:
 
-First steps
------------
-
-Are you new to software documentation?
-Are you looking to use your existing docs with Read the Docs?
-Learn about documentation authoring tools such as Sphinx and MkDocs
-to help you create fantastic documentation for your project.
-
-* **Tutorial**: :doc:`/tutorial/index`
-
-* **Getting started**:
-  :doc:`With Sphinx </intro/getting-started-with-sphinx>` |
-  :doc:`With MkDocs </intro/getting-started-with-mkdocs>` |
-  :doc:`/choosing-a-site`
+.. descriptions here are active
 
-* **Importing your existing documentation**:
-  :doc:`Import guide </intro/import-guide>`
+🚀 :doc:`/tutorial/index`
+  Take the first practical steps with Read the Docs.
 
-Read the Docs feature overview
-------------------------------
+🚀 :doc:`/examples`
+  Start your journey with an example project to hit the ground running.
 
-Learn more about configuring your automated documentation builds
-and some of the core features of Read the Docs.
+.. TODO: This next item needs its article to be finished in a separate PR
+.. https://github.com/readthedocs/readthedocs.org/pull/10071
+.. This page isn't ready for front page treatment
+.. doc:`Why use a dedicated documentation platform? </integrations>`
+.. An introduction to some of the most important reasons for using a *Documentation CI* and build *docs as code*.
 
-* **Overview of core features**:
-  :doc:`/custom-domains` |
-  :doc:`/versions` |
-  :doc:`/downloadable-documentation` |
-  :doc:`/server-side-search/index` |
-  :doc:`/analytics` |
-  :doc:`/pull-requests` |
-  :doc:`/build-notifications` |
-  :doc:`/user-defined-redirects` |
-  :doc:`/security-log`
+:doc:`🚀 All tutorials </tutorials/index>`
+  Using documentation tools like Sphinx or MkDocs for the first time or importing an existing project?
+  We have the tutorials to get you started!
 
-* **Connecting with GitHub, Bitbucket, or GitLab**:
-  :doc:`Connecting your VCS account </connected-accounts>`
-
-* **Read the Docs build process**:
-  :doc:`Configuration reference </config-file/index>` |
-  :doc:`Build process </builds>` |
-  :doc:`Build customization </build-customization>` |
-  :doc:`/environment-variables` |
-  :doc:`/reference/environment-variables` |
-  :doc:`/badges`
-
-* **Troubleshooting**:
-  :doc:`/support` |
-  :doc:`/faq`
+Explanation
+-----------
 
+Get a high-level overview of our platform:
 
-Advanced features of Read the Docs
-----------------------------------
+.. Descriptions here are focused on learning
 
-Read the Docs offers many advanced features and options.
-Learn more about these integrations and how you can get the most
-out of your documentation and Read the Docs.
+.. TODO: This next item needs its article to be finished in a separate PR
+.. https://github.com/readthedocs/readthedocs.org/pull/10071
 
-* **Advanced project configuration**:
-  :doc:`subprojects` |
-  :doc:`Single version docs <single-version>` |
-  :doc:`flyout-menu` |
-  :doc:`feature-flags`
+💡 :doc:`Continuous Documentation </integrations>`
+  Discover the advantages of having your documentation continuously deployed.
 
-* **Multi-language documentation**:
-  :doc:`Translations and localization <localization>`
+💡 :doc:`/choosing-a-site`
+  Learn about the differences between |org_brand| and |com_brand|.
 
-* **Versions**
-  :doc:`Automation rules <automation-rules>`
+.. TODO: This next item needs its article to be finished in a separate PR
+.. https://github.com/readthedocs/readthedocs.org/pull/10071
+.. TODO: 💡 Advanced topics: Deep-dive into Read the Docs
+..  Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs.
 
-* **Topic specific guides**:
-  :doc:`How-to guides <guides/index>`
 
-* **Extending Read the Docs**:
-  :doc:`REST API <api/index>`
+How-to guides
+-------------
 
+Need to get something specific done? These guides provide step-by-step instructions on various areas:
 
+.. Descriptions here are active, learn, setup, etc.
+.. The chosen sample of how-tos is intended reflect to width of the how-to section
+.. i.e. NOT only what is most popular or easiest for beginners.
 
-Read the Docs for Business
---------------------------
+🪄 :doc:`/guides/pull-requests`
+  Setup pull request builds and enjoy previews of each commit.
 
-Read the Docs has a commercial offering with improved support and additional features.
+🪄 :doc:`/analytics`
+  Learn more about how users are interacting with your documentation.
 
-* **Read the Docs for Business**:
-  :doc:`Organizations <commercial/organizations>` |
-  :doc:`Single sign on <commercial/single-sign-on>` |
-  :doc:`Project privacy level <commercial/privacy-level>` |
-  :doc:`Sharing externally <commercial/sharing>`
+🪄 :doc:`/guides/cross-referencing-with-sphinx`
+  Learn how to use cross-references in a Sphinx project.
 
+🪄 :doc:`All how-to guides </guides/index>`
+  Browser the entire catalog for many more how-to guides.
 
-The Read the Docs project and organization
-------------------------------------------
+Reference
+---------
 
-Learn about Read the Docs, the project and the company,
-and find out how you can get involved and contribute to the development and success
-of Read the Docs and the larger software documentation ecosystem.
+Need to know how something works? Our references provide the details:
 
-* **Policies & Process**:
-  :doc:`security` |
-  :doc:`DMCA takedown policy <dmca/index>` |
-  :doc:`/abandoned-projects` |
-  :doc:`/unofficial-projects` |
-  :doc:`Release notes & changelog <changelog>`
+.. Descriptions here sound like reference
 
+📚 :doc:`/reference/features`
+  Overview of all the main features of Read the Docs.
 
-* **The people and philosophy behind Read the Docs**:
-  :doc:`About us </about/index>` |
-  :doc:`Team <team>` |
-  :doc:`Open source philosophy <open-source-philosophy>` |
-  :doc:`Our story <story>`
+📚 :doc:`/config-file/index`
+  Information for our configuration file: ``.readthedocs.yaml``.
 
-* **Financial and material support**:
-  :doc:`advertising/index` |
-  :doc:`Sponsors <sponsors>`
+📚 :doc:`/builds`
+  Overview of how documentation builds happen.
 
-* **Legal documents**:
-  :doc:`Terms of service <terms-of-service>` |
-  :doc:`Privacy policy <privacy-policy>` |
-  :doc:`Data processing agreement <legal/dpa/index>`
+📚 :doc:`/build-customization`
+  Information on how to add your own build logic or replace default build steps.
 
-* **Getting involved with Read the Docs**:
-  :doc:`/glossary` |
-  :doc:`Developer documentation <rtd-dev:index>`
+📚 :doc:`/api/index`
+  Automate your documentation with our API and save yourself some work.