Merge branch 'master' into sss-integration-guide

Author: stsewd

CHANGELOG.rst

@@ -1,3 +1,14 @@
+Version 5.1.5
+-------------
+
+:Date: July 01, 2020
+
+* `@choldgraf <https://github.com/choldgraf>`__: cross-linking build limitations for pr builds (`#7248 <https://github.com/readthedocs/readthedocs.org/pull/7248>`__)
+* `@humitos <https://github.com/humitos>`__: Allow to extend Import Project page from corporate (`#7234 <https://github.com/readthedocs/readthedocs.org/pull/7234>`__)
+* `@humitos <https://github.com/humitos>`__: Make RemoteRepository.full_name db_index=True (`#7231 <https://github.com/readthedocs/readthedocs.org/pull/7231>`__)
+* `@stsewd <https://github.com/stsewd>`__: Search: tweak fuzziness (`#7225 <https://github.com/readthedocs/readthedocs.org/pull/7225>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Re-add the rst filter that got removed (`#7223 <https://github.com/readthedocs/readthedocs.org/pull/7223>`__)
+
 Version 5.1.4
 -------------
 

docs/config-file/v2.rst

@@ -25,7 +25,7 @@ Below is an example YAML file which shows the most common configuration options:
     #  configuration: mkdocs.yml
 
     # Optionally build your docs in additional formats such as PDF
-    formats: 
+    formats:
       - pdf
 
     # Optionally set the version of Python and requirements required to build your docs
@@ -74,11 +74,15 @@ Example:
 
 .. code-block:: yaml
 
+   version: 2
+
    # Default
    formats: []
 
 .. code-block:: yaml
 
+   version: 2
+
    # Build PDF & ePub
    formats:
      - epub
@@ -90,6 +94,8 @@ Example:
 
    .. code-block:: yaml
 
+      version: 2
+
       # Build all formats
       formats: all
 
@@ -104,6 +110,8 @@ Configuration of the Python environment to be used.
 
 .. code-block:: yaml
 
+   version: 2
+
    python:
       version: 3.7
       install:
@@ -153,6 +161,8 @@ Example:
 
 .. code-block:: yaml
 
+   version: 2
+
    python:
       version: 3.7
       install:
@@ -199,6 +209,8 @@ Example:
 
 .. code-block:: yaml
 
+   version: 2
+
    python:
       version: 3.7
       install:
@@ -242,6 +254,8 @@ Configuration for Conda support.
 
 .. code-block:: yaml
 
+   version: 2
+
    conda:
      environment: environment.yml
 
@@ -260,6 +274,8 @@ Configuration for the documentation build process.
 
 .. code-block:: yaml
 
+   version: 2
+
    build:
      image: latest
 
@@ -290,6 +306,8 @@ Configuration for Sphinx documentation
 
 .. code-block:: yaml
 
+   version: 2
+
    sphinx:
      builder: html
      configuration: conf.py
@@ -335,6 +353,8 @@ Configuration for Mkdocs documentation.
 
 .. code-block:: yaml
 
+   version: 2
+
    mkdocs:
      configuration: mkdocs.yml
      fail_on_warning: false
@@ -374,6 +394,8 @@ VCS submodules configuration.
 
 .. code-block:: yaml
 
+   version: 2
+
    submodules:
      include:
         - one
@@ -394,6 +416,8 @@ List of submodules to be included.
 
    .. code-block:: yaml
 
+      version: 2
+
       submodules:
         include: all
 
@@ -412,6 +436,8 @@ List of submodules to be excluded.
 
    .. code-block:: yaml
 
+      version: 2
+
       submodules:
         exclude: all
 
@@ -427,6 +453,65 @@ Do a recursive clone of the submodules.
 
    This is ignored if there aren't submodules to clone.
 
+search
+~~~~~~
+
+Settings for more control over :doc:`/server-side-search`.
+
+.. code-block:: yaml
+
+   version: 2
+
+   search:
+      ranking:
+        api/v1/*: -1
+        api/v2/*: 4
+
+search.ranking
+``````````````
+
+Set a custom search rank over pages matching a pattern.
+
+:Type: ``map`` of patterns to ranks
+:Default: ``{}``
+
+Patterns are matched against the final html pages produced by the build
+(you should try to match `index.html`, not `docs/index.rst`).
+Patterns can include some special characters:
+
+- ``*`` matches everything
+- ``?`` matches any single character
+- ``[seq]`` matches any character in ``seq``
+
+The rank can be an integer number between -10 and 10 (inclusive).
+Pages with a rank closer to -10 will appear further down the list of results,
+and pages with a rank closer to 10 will appear higher in the list of results.
+Note that 0 means *normal rank*, not *no rank*.
+
+.. code-block:: yaml
+
+   version: 2
+
+   search:
+      ranking:
+        # Match a single file
+        tutorial.hml: 2
+
+        # Match all files under the api/v1 directory
+        api/v1/*: -5
+
+        # Match all files that end with tutorial.html
+        */tutorial.html: 3
+
+.. note::
+
+   The final rank will be the last pattern to match the page.
+
+.. tip::
+
+   Is better to decrease the rank of pages you want to deprecate,
+   rather than increasing the rank of the other pages.
+
 Schema
 ------
 
@@ -468,6 +553,7 @@ New settings
 - :ref:`config-file/v2:mkdocs`
 - :ref:`config-file/v2:submodules`
 - :ref:`config-file/v2:python.install`
+- :ref:`config-file/v2:search`
 
 Migrating from the web interface
 --------------------------------

docs/guides/autobuild-docs-for-pull-requests.rst

@@ -50,6 +50,9 @@ Features
 Limitations
 -----------
 
+Auto-builds for pull/merge requests have
+:doc:`the same limitations as regular documentation builds </builds>`.
+
 Currently we don't index search for pull request builds.
 Searches will default to the default experience for your tool.
 This is a feature we plan to add,

docs/guides/searching-with-readthedocs.rst

@@ -2,7 +2,7 @@ Searching with Read the Docs
 ============================
 
 Read the Docs uses :doc:`/server-side-search` to power our search.
-This guide explains how to add a "search as you type" feature to your documentation, 
+This guide explains how to add a "search as you type" feature to your documentation,
 and how to use advanced query syntax to get more accurate results.
 
 You can find information on the search architecture and how we index documents in our
@@ -20,7 +20,7 @@ Enable "search as you type" in your documentation
 documentation more closely with the search implementation of Read the Docs.
 It adds a clean and minimal full-page search UI that supports a **search as you type** feature.
 
-To try this feature, 
+To try this feature,
 you can press :guilabel:`/` (forward slash) and start typing or just visit these URLs:
 
 - https://docs.readthedocs.io/?rtd_search=contributing

docs/server-side-search.rst

@@ -25,7 +25,12 @@ Search results land on the exact content you were looking for
    We index every heading in the document,
    allowing you to get search results exactly to the content that you are searching for.
    Try this out by searching for `"full-text search"`_.
-   
+
+Full control over which results should be listed first
+   Set a custom rank per page,
+   allowing you to deprecate content, and always show relevant content to your users first.
+   See :ref:`config-file/v2:search.ranking`.
+
 Search across projects you have access to (|com_brand|)
    This allows you to search across all the projects you access to in your Dashboard.
    **Don't remember where you found that document the other day?
@@ -35,10 +40,10 @@ Special query syntax for more specific results.
    We support a full range of search queries.
    You can see some examples in our :ref:`guides/searching-with-readthedocs:search query syntax` guide.
 
-.. 
+..
    Code object searching
       With the user of :doc:`Sphinx Domains <sphinx:/usage/restructuredtext/domains>` we are able to automatically provide direct search results to your Code objects.
-      You can try this out with our docs here by searching for 
+      You can try this out with our docs here by searching for
       TODO: Find good examples in our docs, API maybe?
 
 .. _"full-text search": https://docs.readthedocs.io/en/latest/search.html?q=%22full-text+search%22

readthedocs/api/v2/views/integrations.py

@@ -407,6 +407,7 @@ def handle_webhook(self):
 
         # Sync versions when a branch/tag was created/deleted
         if event in (GITHUB_CREATE, GITHUB_DELETE):
+            log.info('Triggered sync_versions: project=%s event=%s', self.project, event)
             return self.sync_versions_response(self.project)
 
         # Handle pull request events
@@ -447,6 +448,7 @@ def handle_webhook(self):
                 # already have the CREATE/DELETE events. So we don't trigger the sync twice.
                 return self.sync_versions_response(self.project, sync=False)
 
+            log.info('Triggered sync_versions: project=%s events=%s', self.project, events)
             return self.sync_versions_response(self.project)
 
         # Trigger a build for all branches in the push
@@ -559,6 +561,8 @@ def handle_webhook(self):
             after = data['after']
             # Tag/branch created/deleted
             if GITLAB_NULL_HASH in (before, after):
+                log.info('Triggered sync_versions: project=%s before=%s after=%s',
+                         self.project, before, after)
                 return self.sync_versions_response(self.project)
             # Normal push to master
             try:
@@ -659,6 +663,8 @@ def handle_webhook(self):
                 # will be triggered with the normal push.
                 if branches:
                     return self.get_response_push(self.project, branches)
+                log.info('Triggered sync_versions: project=%s event=%s',
+                         self.project, event)
                 return self.sync_versions_response(self.project)
             except KeyError:
                 raise ParseError('Invalid request')