Merge tag '6.3.1' into rel

Author: ericholscher

.readthedocs.yml

@@ -1,12 +1,20 @@
 version: 2
+
 formats: all
+
 sphinx:
   configuration: docs/conf.py
+
 python:
   install:
     - requirements: requirements/pip.txt
     - requirements: requirements/docs.txt
 
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+
 search:
   ignore:
     # Internal documentation

CHANGELOG.rst

@@ -1,3 +1,32 @@
+Version 6.3.1
+-------------
+
+:Date: December 14, 2021
+
+* `@stsewd <https://github.com/stsewd>`__: Explicit settings for some tests (`#8759 <https://github.com/readthedocs/readthedocs.org/pull/8759>`__)
+* `@stsewd <https://github.com/stsewd>`__: Don't run spam rules check after ban action (`#8756 <https://github.com/readthedocs/readthedocs.org/pull/8756>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Add MyST Markdown examples everywhere (`#8752 <https://github.com/readthedocs/readthedocs.org/pull/8752>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Update mambaforge to latest version (`#8749 <https://github.com/readthedocs/readthedocs.org/pull/8749>`__)
+* `@stsewd <https://github.com/stsewd>`__: Update django (`#8748 <https://github.com/readthedocs/readthedocs.org/pull/8748>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Remove sphinx-doc.org from external domains (`#8747 <https://github.com/readthedocs/readthedocs.org/pull/8747>`__)
+* `@stsewd <https://github.com/stsewd>`__: Fix call to sync_remote_repositories (`#8742 <https://github.com/readthedocs/readthedocs.org/pull/8742>`__)
+* `@stsewd <https://github.com/stsewd>`__: Tests: set privacy level explicitly (`#8740 <https://github.com/readthedocs/readthedocs.org/pull/8740>`__)
+* `@humitos <https://github.com/humitos>`__: Spam: contact link on template (`#8739 <https://github.com/readthedocs/readthedocs.org/pull/8739>`__)
+* `@humitos <https://github.com/humitos>`__: Spam: fix admin filter (`#8738 <https://github.com/readthedocs/readthedocs.org/pull/8738>`__)
+* `@stsewd <https://github.com/stsewd>`__: Always clear cache after each test (`#8737 <https://github.com/readthedocs/readthedocs.org/pull/8737>`__)
+* `@humitos <https://github.com/humitos>`__: Logging: tweaks and minor improvements (`#8736 <https://github.com/readthedocs/readthedocs.org/pull/8736>`__)
+* `@humitos <https://github.com/humitos>`__: Logs: typo on keyname (`#8734 <https://github.com/readthedocs/readthedocs.org/pull/8734>`__)
+* `@humitos <https://github.com/humitos>`__: Log: use structlog-sentry to send logs to Sentry (`#8732 <https://github.com/readthedocs/readthedocs.org/pull/8732>`__)
+* `@humitos <https://github.com/humitos>`__: docs: use Python 3.8 to build our docs (`#8731 <https://github.com/readthedocs/readthedocs.org/pull/8731>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Release 6.3.0 (`#8730 <https://github.com/readthedocs/readthedocs.org/pull/8730>`__)
+* `@stsewd <https://github.com/stsewd>`__: Custom Domain: make cname_target configurable (`#8728 <https://github.com/readthedocs/readthedocs.org/pull/8728>`__)
+* `@stsewd <https://github.com/stsewd>`__: Test external serving for projects with `--` in slug (`#8716 <https://github.com/readthedocs/readthedocs.org/pull/8716>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Add guide to migrate from reST to MyST (`#8714 <https://github.com/readthedocs/readthedocs.org/pull/8714>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Avoid future breakage of `setup.py` invokations (`#8711 <https://github.com/readthedocs/readthedocs.org/pull/8711>`__)
+* `@humitos <https://github.com/humitos>`__: structlog: migrate application code to better logging (`#8705 <https://github.com/readthedocs/readthedocs.org/pull/8705>`__)
+* `@humitos <https://github.com/humitos>`__: EmbedAPI: log success requests (`#8689 <https://github.com/readthedocs/readthedocs.org/pull/8689>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add ability to rebuild a specific build (`#6995 <https://github.com/readthedocs/readthedocs.org/pull/6995>`__)
+
 Version 6.3.0
 -------------
 

docs/advertising/ethical-advertising.rst

@@ -1,5 +1,5 @@
-Ethical Ads
-===========
+EthicalAds
+==========
 
 .. meta::
    :description lang=en: To fund Read the Docs, we built an ad platform that doesn't track users and respects their privacy.
@@ -8,9 +8,9 @@ Ethical Ads
 Read the Docs is a large, free web service.
 There is one proven business model to support this kind of site: **Advertising**.
 We are building the advertising model we want to exist,
-and we're calling it **Ethical Ads**.
+and we're calling it **EthicalAds**.
 
-**Ethical Ads respect users while providing value to advertisers.**
+**EthicalAds respect users while providing value to advertisers.**
 We don't track you, sell your data, or anything else.
 We simply show ads to users, based on the content of the pages you look at.
 We also give 10% of our ad space to :ref:`community projects <advertising/ethical-advertising:Community Ads>`,

docs/conf.py

@@ -35,6 +35,7 @@ def get_version():
     'hoverxref.extension',
     'sphinx_search.extension',
     'sphinxemoji.sphinxemoji',
+    'myst_parser',
 ]
 
 templates_path = ['_templates']
@@ -63,7 +64,12 @@ def get_version():
     'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
     'writethedocs': ('https://www.writethedocs.org/', None),
     'jupyterbook': ('https://jupyterbook.org/', None),
+    'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
+    'rst-to-myst': ('https://rst-to-myst.readthedocs.io/en/stable/', None),
 }
+myst_enable_extensions = [
+    "deflist",
+]
 hoverxref_intersphinx = [
    "sphinx",
    "pip",

docs/guides/authors.rst

@@ -16,3 +16,4 @@ and :doc:`/intro/getting-started-with-mkdocs`.
    cross-referencing-with-sphinx
    intersphinx
    jupyter
+   migrate-rest-myst

docs/guides/embedding-content.rst

@@ -79,17 +79,33 @@ and show a modal when the user clicks in a "Help" link.
     To avoid that, you can manually define Sphinx references above the sections you don't want to break.
     For example,
 
-    .. code-block:: rst
-       :emphasize-lines: 3
+    .. tabs::
 
-       .. in your .rst document file
+       .. tab:: reStructuredText
 
-       .. _unbreakable-section-reference:
+          .. code-block:: rst
+             :emphasize-lines: 3
 
-       Creating an automation rule
-       ---------------------------
+             .. in your .rst document file
 
-       This is the text of the section.
+             .. _unbreakable-section-reference:
+
+             Creating an automation rule
+             ---------------------------
+
+             This is the text of the section.
+
+       .. tab:: MyST (Markdown)
+
+          .. code-block:: md
+             :emphasize-lines: 3
+
+             .. in your .md document file
+
+             (unbreakable-section-reference)=
+             ## Creating an automation rule
+
+             This is the text of the section.
 
     To link to the section "Creating an automation rule" you can send ``section=unbreakable-section-reference``.
     If you change the title it won't break the embedded content because the label for that title will still be ``unbreakable-section-reference``.

docs/guides/jupyter.rst

@@ -58,13 +58,29 @@ Next, you will need to enable one of the extensions, as follows:
 Finally, you can include the notebook in any *toctree*.
 For example, add this to your root document:
 
-.. code-block:: rest
+.. tabs::
+
+   .. tab:: reStructuredText
+
+      .. code-block:: rst
+
+         .. toctree::
+            :maxdepth: 2
+            :caption: Contents:
 
-   .. toctree::
-      :maxdepth: 2
-      :caption: Contents:
+            notebooks/Example 1
 
-      notebooks/Example 1
+   .. tab:: MyST (Markdown)
+
+      .. code-block:: md
+
+         ```{toctree}
+         ---
+         maxdepth: 2
+         caption: Contents:
+         ---
+         notebooks/Example 1
+         ```
 
 The notebook will render as any other HTML page in your documentation
 after doing ``make html``.
@@ -255,14 +271,29 @@ For example, this reST markup would create a thumbnail gallery
 with generic images as thumbnails,
 thanks to the Sphinx-Gallery default style:
 
-.. code-block:: rest
+.. tabs::
+
+   .. tab:: reStructuredText
+
+      .. code-block:: rst
+
+         Thumbnails gallery
+         ==================
+
+         .. nbgallery::
+            notebooks/Example 1
+            notebooks/Example 2
+
+   .. tab:: MyST (Markdown)
+
+      .. code-block:: md
 
-   Thumbnails gallery
-   ==================
+         # Thumbnails gallery
 
-   .. nbgallery::
-      notebooks/Example 1
-      notebooks/Example 2
+         ```{nbgallery}
+         notebooks/Example 1
+         notebooks/Example 2
+         ```
 
 .. figure:: /_static/images/guides/thumbnail-gallery.png
    :width: 80%

docs/guides/migrate-rest-myst.md

@@ -0,0 +1,141 @@
+# Migrating from reStructuredText to MyST Markdown
+
+Sphinx is usually associated with reStructuredText, the markup language
+{pep}`designed for the CPython project in the early '00s <287>`.
+However, for quite some time Sphinx has been compatible with Markdown as well,
+thanks to a number of extensions.
+
+The most powerful of such extensions is {doc}`MyST-Parser <myst-parser:index>`,
+which implements a CommonMark-compliant, extensible Markdown dialect
+with support for the Sphinx roles and directives that make it so useful.
+In this guide, you will find
+how you can start writing Markdown in your existing reStructuredText project,
+or migrate it completely.
+
+If, instead of migrating, you are starting a new project from scratch,
+have a look at {doc}`myst-parser:sphinx/intro`.
+
+## Writing your content both in reStructuredText and MyST
+
+It is useful to ask whether a migration is necessary in the first place.
+Doing bulk migrations of large projects with lots of work in progress
+will create conflicts for ongoing changes.
+On the other hand, your writers might prefer to have some files in Markdown
+and some others in reStructuredText, for whatever reason.
+Luckily, Sphinx supports reading both types of markup at the same time without problems.
+
+To start using MyST in your existing Sphinx project,
+first {ref}``install the `myst-parser` Python package <myst-parser:sphinx/intro.md#install-the-myst-parser>``
+and then {ref}`enable it on your configuration <myst-parser:parse-with-sphinx>`:
+
+```{code-block} py
+:caption: conf.py
+:emphasize-lines: 4
+
+extensions = [
+    # Your existing extensions
+    ...,
+    "myst_parser",
+]
+```
+
+Your reStructuredText documents will keep rendering,
+and you will be able to add MyST documents with the `.md` extension
+that will be processed by MyST-Parser.
+
+As an example, _this guide_ is written in MyST
+while the rest of the Read the Docs documentation is written in reStructuredText.
+
+```{note}
+By default, MyST-Parser registers the `.md` suffix for MyST source files.
+If you want to use a different suffix, you can do so by changing your
+`source_suffix` configuration value in `conf.py`.
+```
+
+## Converting existing reStructuredText documentation to MyST
+
+To convert existing reST documents to MyST, you can use
+the `rst2myst` CLI script shipped by {doc}`rst-to-myst:index`.
+The script supports converting the documents one by one,
+or scanning a series of directories to convert them in bulk.
+
+After {doc}``installing `rst-to-myst` <rst-to-myst:index>``,
+you can run the script as follows:
+
+```console
+$ rst2myst convert docs/source/index.rst  # Converts index.rst to index.md
+$ rst2myst convert docs/**/*.rst  # Convert every .rst file under the docs directory
+```
+
+This will create a `.md` MyST file for every `.rst` source file converted.
+
+### Advanced usage of `rst2myst`
+
+The `rst2myst` accepts several flags to modify its behavior.
+All of them have sensible defaults, so you don't have to specify them
+unless you want to.
+
+These are a few options you might find useful:
+
+{option}``-d, --dry-run <rst-to-myst:rst2myst-convert.--dry-run>``
+: Only verify that the script would work correctly,
+  without actually writing any files.
+
+{option}``-R, --replace-files <rst-to-myst:rst2myst-convert.--replace-files>``
+: Replace the `.rst` files by their `.md` equivalent,
+  rather than writing a new `.md` file next to the old `.rst` one.
+
+You can read the full list of options in
+{doc}``the `rst2myst` documentation <rst-to-myst:cli>``.
+
+## Enabling optional syntax
+
+Some reStructuredText syntax will require you to enable certain MyST plugins.
+For example, to write [reST definition lists], you need to add a
+`myst_enable_extensions` variable to your Sphinx configuration, as follows:
+
+```{code-block} py
+:caption: conf.py
+myst_enable_extensions = [
+    "deflist",
+]
+```
+
+You can learn more about {doc}`other MyST-Parser plugins <myst-parser:syntax/optional>`
+in their documentation.
+
+[reST definition lists]: https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
+
+## Writing reStructuredText syntax within MyST
+
+There is a small chance that `rst2myst` does not properly understand a piece of reST syntax,
+either because there is a bug in the tool
+or because that syntax does not have a MyST equivalent yet.
+For example, {ref}`as explained in the documentation <myst-parser:howto/autodoc>`,
+the `sphinx.ext.autodoc` extension is incompatible with MyST.
+
+Fortunately, MyST supports an `eval-rst` directive
+that will parse the content as reStructuredText, rather than MyST.
+For example:
+
+````
+```{eval-rst}
+.. note::
+
+   Complete MyST migration.
+
+```
+````
+
+will produce the following result:
+
+```{eval-rst}
+.. note::
+
+   Complete MyST migration.
+
+```
+
+As a result, this allows you to conduct a gradual migration,
+at the expense of having heterogeneous syntax in your source files.
+In any case, the HTML output will be the same.