diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 8a102ab2b08..a853a5efde8 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,3 +1,27 @@ +Version 10.1.0 +-------------- + +:Date: August 22, 2023 + +* `@ecormany `__: docs: typo fix on "Custom and built-in redirects" page (`#10651 `__) +* `@humitos `__: Celery: use django-celery-beat scheduler (`#10647 `__) +* `@humitos `__: Build: drop websupport2 support from conf.py template (`#10646 `__) +* `@ericholscher `__: Remove the celery email tasks until we can debug them. (`#10641 `__) +* `@humitos `__: Development: disable cached Loader on `DEBUG=True` (`#10640 `__) +* `@humitos `__: Docs: update tutorial with the latest required changes (`#10639 `__) +* `@humitos `__: Build: do not set `sphinx_rtd_theme` theme automatically (`#10638 `__) +* `@humitos `__: Build: update links to blog post (`#10636 `__) +* `@stsewd `__: Proxito: allow to generate proxied API URLs with a prefix (`#10634 `__) +* `@ericholscher `__: Small wording cleanup on Integration howto (`#10632 `__) +* `@github-actions[bot] `__: Dependencies: all packages updated via pip-tools (`#10628 `__) +* `@humitos `__: Black: run black over all the code base (`#10619 `__) +* `@humitos `__: Revert "Contact projects with a build in the last 3 years" (`#10618 `__) +* `@humitos `__: Settings: remove CSRF_COOKIE_MASKED (`#10608 `__) +* `@stsewd `__: Versions: keep type of version in sync with the project (`#10606 `__) +* `@humitos `__: Import: remove extra/advanced step from project import wizard (`#10603 `__) +* `@benjaoming `__: Docs: Methodology section (`#10417 `__) +* `@humitos `__: VCS: remove unused methods and make new Git pattern the default (`#8968 `__) + Version 10.0.0 -------------- diff --git a/docs/conf.py b/docs/conf.py index e65e62b1e19..3022f86204c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -77,7 +77,7 @@ master_doc = "index" copyright = "Read the Docs, Inc & contributors" -version = "10.0.0" +version = "10.1.0" release = version exclude_patterns = ["_build", "shared", "_includes"] default_role = "obj" diff --git a/docs/user/_static/images/tutorial/github-template.png b/docs/user/_static/images/tutorial/github-template.png index 936e4ac13e5..e17f846dd6c 100644 Binary files a/docs/user/_static/images/tutorial/github-template.png and b/docs/user/_static/images/tutorial/github-template.png differ diff --git a/docs/user/explanation/documentation-structure.rst b/docs/user/explanation/documentation-structure.rst new file mode 100644 index 00000000000..63fe12972cb --- /dev/null +++ b/docs/user/explanation/documentation-structure.rst @@ -0,0 +1,50 @@ +How to structure your documentation +=================================== + +A documentation project's ultimate goal is to be read and understood by a reader. +Readers need to be able to :term:`discover ` the information that they need. +Without an defined structure, +readers either won't find information that they need or get frustrated on the way. + +One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. +Starting with a blank page is often the hardest part of documentation, +so anything we can do to remove this problem is a win. + +Choosing a structure +-------------------- + +Good news! +You don't have to invent all of the structure yourself, +since a lot of experience-based work has been done to come up with a universal documentation structure. + +In order to avoid starting with a blank page, +we recommend a simple process: + +* Choose a structure for your documentation. We recommend `Diátaxis `_ for this. +* Find a :doc:`example project ` or template to start from. +* Start writing by filling in the structure. + +This process helps you get started quickly, +and helps keep things consistent for the reader of your documentation. + +.. _diataxis: + +Diátaxis Methodology +-------------------- + +The documentation you're reading is written using the Diátaxis framework. +It has four major parts as summarized by this image: + +.. image:: https://diataxis.fr/_images/diataxis.png + +We recommend that you read more about it in the `official Diátaxis documentation `_. + +Explaining the structure to your users +-------------------------------------- + +One of the benefits of Diátaxis is that it's a well-known structure, +and users might already be familiar with it. +As long as you stick to the structure, +your users should be able to use existing experience to navigate. + +Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here. diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst new file mode 100644 index 00000000000..b8a8930fc5d --- /dev/null +++ b/docs/user/explanation/methodology.rst @@ -0,0 +1,37 @@ +Methodology and best practice +============================= + +In this section, +we are covering important methods and best practices that will make your documentation better. + +.. seealso:: + + `Write the Docs: Topic Archive `__ + A collection of conference talks and articles, + indexed by topic (eg. ``Metrics and analytics`` or ``Information architecture``) + +You can familiarize yourself with these topics before or after writing documentation. +We encourage that you read this at any time, +as this content is applicable to many stages of the documentation process. + +⏩️ :doc:`The Diátaxis Methodology ` + We introduce the Diátaxis methodology which is also used for the documentation you are now reading. + +⏩️ :doc:`Creating reproducible builds ` + Every documentation project has dependencies that are required to build it. + Using an unspecified versions of these dependencies means that your project can start breaking. + In this guide, + learn how to protect your project against breaking randomly. + **This is one of our most popular guides!** + +⏩️ :doc:`Search engine optimization (SEO) for documentation projects ` + This article explains how documentation can be optimized to appear in search results, + increasing traffic to your docs. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + documentation-structure + /guides/best-practice/index diff --git a/docs/user/guides/setup/git-repo-manual.rst b/docs/user/guides/setup/git-repo-manual.rst index 89385018a63..d454a965b2c 100644 --- a/docs/user/guides/setup/git-repo-manual.rst +++ b/docs/user/guides/setup/git-repo-manual.rst @@ -1,9 +1,9 @@ -How to manually configure a Git repository -========================================== +How to manually configure a Git repository integration +====================================================== In this guide, -you will find the simple steps to manually integrating your Read the Docs project with all Git providers that support our generic API. -This includes most Git providers, for example |git_providers_and|. +you will find the steps to manually integrate your Read the Docs project with any Git provider, +including |git_providers_and|. .. seealso:: @@ -12,7 +12,6 @@ This includes most Git providers, for example |git_providers_and|. If your Read the Docs account is :doc:`connected to the Git provider `, we can setup the integration automatically. - .. The following references were supposed to go inside tabs, which is supported here: @@ -29,11 +28,11 @@ This includes most Git providers, for example |git_providers_and|. .. _webhook-integration-bitbucket: .. _webhook-integration-gitlab: -Provider-specific instructions ------------------------------- +Manual integration setup +------------------------ -You need to configure your Git provider to call a webhook on Read the Docs. -This will make Read the Docs build your documentation when a new commit, branch or tag is pushed to your repository. +You need to configure your Git provider integration to call a webhook that alerts Read the Docs of changes. +Read the Docs will sync versions and build your documentation when your Git repository is updated. .. tabs:: @@ -128,8 +127,7 @@ After you have added the integration, you'll see a link to information about the As an example, the URL pattern looks like this: ``https://readthedocs.org/api/v2/webhook///*``. -Use this URL when setting up a new integration with your provider ^^ these steps vary depending on the provider. - +Use this URL when setting up a new integration with your provider, as explained above. .. warning:: diff --git a/docs/user/index.rst b/docs/user/index.rst index e73a99df621..5be7ee165e6 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -20,7 +20,12 @@ Read the Docs: documentation simplified /choosing-a-site /integrations + /downloadable-documentation + /environment-variables + /subprojects + /localization /explanation/advanced + /explanation/methodology .. toctree:: :maxdepth: 2 diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 55af5deed97..0221159a1b7 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -38,6 +38,10 @@ which will generate a new repository on your personal account This is the repository you will import on Read the Docs, and it contains the following files: +``.readthedocs.yaml`` + Read the Docs configuration file. + Required to setup the documentation build process. + ``README.rst`` Basic description of the repository, you will leave it untouched. @@ -147,15 +151,9 @@ Name Repository URL The URL that contains the sources. Leave the automatically filled value. -Repository type - Version control system used, leave it as "Git". - Default branch Name of the default branch of the project, leave it as ``main``. -Edit advanced project options - Leave it unchecked, we will make some changes later. - After hitting the :guilabel:`Next` button, you will be redirected to the :term:`project home`. You just created your first project on Read the Docs! |:tada:| @@ -287,13 +285,7 @@ When you are satisfied, you can merge the pull request! Adding a configuration file --------------------------- -As of September 2023, -:doc:`you will need to add a configuration file to build your documentation `. -Until then, -this example project will build without the configuration file, -but we **strongly recommend** completing this section in order to add a configuration file. - -The Settings page of the :term:`project home` allows you +The Admin tab of the :term:`project home` allows you to change some *global* configuration values of your project. In addition, you can further customize the building process using the ``.readthedocs.yaml`` :doc:`configuration file `. @@ -316,23 +308,28 @@ In this section, we will show you some examples of what a configuration file sho Settings that apply to the entire project are controlled in the web dashboard, while settings that are version or build specific are better in the YAML file. -Upgrading the Python version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Changing the Python version +~~~~~~~~~~~~~~~~~~~~~~~~~~~ For example, to explicitly use Python 3.8 to build your project, -navigate to your GitHub repository, click on the :guilabel:`Add file` button, -and add a ``.readthedocs.yaml`` file with these contents to the root of your project: +navigate to your GitHub repository, click on ``.readthedocs.yaml`` file and then in the pencil icon ✏️ to edit the file +and change the Python version as follows: .. code-block:: yaml :caption: .readthedocs.yaml + :emphasize-lines: 6 version: 2 build: - os: "ubuntu-20.04" + os: "ubuntu-22.04" tools: python: "3.8" + python: + install: + - requirements: docs/requirements.txt + The purpose of each key is: ``version`` @@ -345,9 +342,12 @@ The purpose of each key is: ``build.tools.python`` Declares the Python version to be used. +``python.install.requirements`` + Specifies the Python dependencies to install required to build the documentation. + After you commit these changes, go back to your project home, navigate to the "Builds" page, and open the new build that just started. -You will notice that one of the lines contains ``python3.8``: +You will notice that one of the lines contains ``python -mvirtualenv``: if you click on it, you will see the full output of the corresponding command, stating that it used Python 3.8.6 to create the virtual environment. @@ -387,15 +387,19 @@ click on the |:pencil2:| icon, and add these contents: .. code-block:: yaml :caption: .readthedocs.yaml - :emphasize-lines: 8-9 + :emphasize-lines: 12-13 version: 2 build: - os: "ubuntu-20.04" + os: "ubuntu-22.04" tools: python: "3.8" + python: + install: + - requirements: docs/requirements.txt + sphinx: fail_on_warning: true @@ -414,11 +418,12 @@ go back to editing ``.readthedocs.yaml`` on GitHub and modify it as follows: .. code-block:: yaml :caption: .readthedocs.yaml - :emphasize-lines: 2-4 + :emphasize-lines: 4-6 python: - # Install our python package before building the docs install: + - requirements: docs/requirements.txt + # Install our python package before building the docs - method: pip path: . @@ -547,36 +552,40 @@ and a new build will be triggered for it. You can read more about :ref:`hidden versions ` in our documentation. -Show a warning for old versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. "Show a warning for old versions" feature is not available anymore. + We should re-write this section once we have the notification addons rolled out. -When your project matures, the number of versions might increase. -Sometimes you will want to warn your readers -when they are browsing an old or outdated version of your documentation. -To showcase how to do that, let's create a ``2.0`` version of the code: -navigate to your GitHub repository, click on the branch selector, -type ``2.0.x``, and click on "Create branch: 2.0.x from 'main'". -This will trigger two things: + Show a warning for old versions + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Since ``2.0.x`` is your newest branch, ``stable`` will switch to tracking it. -- A new ``2.0.x`` version will be created on your Read the Docs project. -- Since you already have an active ``stable`` version, ``2.0.x`` will be activated. + When your project matures, the number of versions might increase. + Sometimes you will want to warn your readers + when they are browsing an old or outdated version of your documentation. -From this point, ``1.0.x`` version is no longer the most up to date one. -To display a warning to your readers, go to the :guilabel:`⚙ Admin` menu of your project home, -click on the :guilabel:`Advanced Settings` link on the left, -enable the "Show version warning" checkbox, and click the :guilabel:`Save` button. + To showcase how to do that, let's create a ``2.0`` version of the code: + navigate to your GitHub repository, click on the branch selector, + type ``2.0.x``, and click on "Create branch: 2.0.x from 'main'". + This will trigger two things: -If you now browse the ``1.0.x`` documentation, you will see a warning on top -encouraging you to browse the latest version instead. Neat! + - Since ``2.0.x`` is your newest branch, ``stable`` will switch to tracking it. + - A new ``2.0.x`` version will be created on your Read the Docs project. + - Since you already have an active ``stable`` version, ``2.0.x`` will be activated. -.. figure:: /_static/images/tutorial/old-version-warning.png - :width: 80% - :align: center - :alt: Warning for old versions + From this point, ``1.0.x`` version is no longer the most up to date one. + To display a warning to your readers, go to the :guilabel:`⚙ Admin` menu of your project home, + click on the :guilabel:`Advanced Settings` link on the left, + enable the "Show version warning" checkbox, and click the :guilabel:`Save` button. + + If you now browse the ``1.0.x`` documentation, you will see a warning on top + encouraging you to browse the latest version instead. Neat! + + .. figure:: /_static/images/tutorial/old-version-warning.png + :width: 80% + :align: center + :alt: Warning for old versions - Warning for old versions + Warning for old versions Getting insights from your projects ----------------------------------- diff --git a/docs/user/user-defined-redirects.rst b/docs/user/user-defined-redirects.rst index a0c55ebaf06..87009c7e25c 100644 --- a/docs/user/user-defined-redirects.rst +++ b/docs/user/user-defined-redirects.rst @@ -159,7 +159,7 @@ You would set the following configuration:: From URL: /example.html To URL: /examples/intro.html -**Page Redirects apply to all versions of you documentation.** +**Page Redirects apply to all versions of your documentation.** Because of this, the ``/`` at the start of the ``From URL`` doesn't include the ``/$lang/$version`` prefix (e.g. ``/en/latest``), but just the version-specific part of the URL. diff --git a/media/javascript/websupport2-bundle.js b/media/javascript/websupport2-bundle.js deleted file mode 100644 index 962305616c0..00000000000 --- a/media/javascript/websupport2-bundle.js +++ /dev/null @@ -1,459 +0,0 @@ -(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o 0 ? settings.opts.commentBrightImage : settings.opts.commentImage; - var addcls = count == 0 ? ' nocomment' : ''; - addCommentIcon(id, title, image, addcls) - } - $.each($('.sphinx-has-comment'), function () { - count = 0 - id = $(this).attr('id') - if (!(id in settings.metadata)) { - var title = count + ' comment' + (count == 1 ? '' : 's'); - var image = count > 0 ? settings.opts.commentBrightImage : settings.opts.commentImage; - var addcls = count == 0 ? ' nocomment' : ''; - addCommentIcon(id, title, image, addcls) - } - }) -} - -function addCommentIcon(id, title, image, addcls) { - $("#" + id) - .append( - $(document.createElement('a')).attr({ - href: '#', - 'class': 'sphinx-comment-open' + addcls, - id: 'comment-open-' + id - }) - .append($(document.createElement('img')).attr({ - src: image, - alt: 'comment', - title: title - })) - - ) - .append( - $(document.createElement('a')).attr({ - href: '#', - 'class': 'sphinx-comment-close hidden', - id: 'comment-close-' + id - }) - .append($(document.createElement('img')).attr({ - src: settings.opts.closeCommentImage, - alt: 'close', - title: 'close' - })) - ); -} - - -function addComment(form) { - var node_id = form.find('input[name="node"]').val(); - var text = form.find('textarea[name="comment"]').val(); - - if (text == '') { - display.showError('Please enter a comment.'); - return; - } - - // Disable the form that is being submitted. - form.find('textarea,input').attr('disabled', 'disabled'); - - - var server_data = getServerData(); - var comment_data = { - node: node_id, - text: text, - }; - var post_data = $.extend(server_data, comment_data) - - - // Send the comment to the server. - $.ajax({ - type: "POST", - url: settings.opts.addCommentURL, - dataType: 'json', - data: post_data, - success: function(data, textStatus, error) { - form.find('textarea') - .val('') - .add(form.find('input')) - .removeAttr('disabled'); - display.showOneComment($(".comment-list"), data) - var comment_element = $('#' + node_id); - comment_element.find('img').attr({'src': settings.opts.commentBrightImage}); - comment_element.find('a').removeClass('nocomment'); - }, - error: function(request, textStatus, error) { - form.find('textarea,input').removeAttr('disabled'); - display.showError('Oops, there was a problem adding the comment.'); - } - }); -} - - -function attachComment(form) { - var node_id = form.find('input[name="node"]').val(); - var comment_id = form.find('input[name="comment"]').val(); - - var server_data = getServerData(); - var comment_data = { - node: node_id, - comment: comment_id - }; - var post_data = $.extend(server_data, comment_data) - - - // Send the comment to the server. - $.ajax({ - type: "POST", - url: settings.opts.attachCommentURL, - dataType: 'json', - data: post_data, - success: function(data, textStatus, error) { - form.find('textarea') - .val('') - .add(form.find('input')) - .removeAttr('disabled'); - display.showOneComment($(".comment-list"), data) - var comment_element = $('#' + node_id); - comment_element.find('img').attr({'src': settings.opts.commentBrightImage}); - comment_element.find('a').removeClass('nocomment'); - }, - error: function(request, textStatus, error) { - form.find('textarea,input').removeAttr('disabled'); - display.showError('Oops, there was a problem adding the comment.'); - } - }); -} - - - -},{"./display":3,"./docpage":4,"./settings":6}],3:[function(require,module,exports){ -module.exports = { - initDisplay: initDisplay, - displayComments: displayComments, - showOneComment: showOneComment, - closeComments: closeComments -} - -comm = require('./comm') - -function initDisplay() { - $('body').append("
"); - $('body').append("
"); -} - -function closeComments() { - $.pageslide.close() -} - -function displayComments(id) { - server_data = comm.getServerData() - get_data = { - 'node': id - } - var post_data = $.extend(get_data, server_data) - delete post_data['page'] - - $.ajax({ - type: 'GET', - url: settings.opts.getCommentsURL, - data: post_data, - crossDomain: true, - xhrFields: { - withCredentials: true, - }, - success: function(data) { - handleComments(id, data) - - }, - error: function(request, textStatus, error) { - showError('Oops, there was a problem retrieving the comments.'); - }, - dataType: 'json' - }); -} - - -function handleComments(id, data) { - showComments(id, data.results) -} - - -function showComments(id, comment_data) { - element = $('#current-comment').html("

Comments

") - element.append("
") - for (index in comment_data) { - obj = comment_data[index] - showOneComment($(".comment-list"), obj) - } - element.append("
") - var reply = '\ -
\ -
\ - \ - \ - \ -
\ -
' - - element.append("
") - $(".comment-div").append(reply) - element.append("
") - - element.append("


") - element.append("
") - element.append("


") - element.append("

Floating Comments

") - element.append("
") - for (index in comment_data) { - obj = comment_data[index] - showOneComment($(".floating-comment-list"), obj) - var attach = '\ -
\ -
\ - \ - \ - \ -
\ -
' - - } - element.append("
") - $(".floating-comment-div").append(attach) - element.append("
") - - element.append("
") - element.append("") - - $.pageslide({direction: 'left', href:'#current-comment' }) -} - -function showOneComment(element, comment) { - console.log("Displaying") - console.log(comment) - to_append = "" - to_append += comment['date'] + "
" - to_append += comment['text'] - to_append += "" - element.append(to_append) -} - - function showError(message) { - $(document.createElement('div')).attr({'class': 'popup-error'}) - .append($(document.createElement('div')) - .attr({'class': 'error-message'}).text(message)) - .appendTo('body') - .fadeIn("slow") - .delay(2000) - .fadeOut("slow"); - } - -// Don't need this since its in the page. - -/* -function setUpPageslide() { - $.ajax({ - url: "https://api.grokthedocs.com/static/javascript/pageslide/jquery.pageslide.js", - crossDomain: true, - dataType: "script", - cache: true, - success: function () { - console.log("Loaded pageslide") - $('head').append(''); - $('body').append("
"); - }, - error: function (e) { - console.log("OMG FAIL:" + e) - } - - }); -} -*/ -},{"./comm":2}],4:[function(require,module,exports){ -// Module exporting page-level variables for easy use -module.exports = { - project: READTHEDOCS_DATA['project'], - version: READTHEDOCS_DATA['version'], - page: getPageName(), - commit: getCommit() -} - -function getPageName() { - if ('page' in READTHEDOCS_DATA) { - return READTHEDOCS_DATA['page'] - } else { - stripped = window.location.pathname.substring(1) - stripped = stripped.replace(".html", "") - stripped = stripped.replace(/\/$/, "") - return stripped - } -} - -function getCommit() { - if ('commit' in READTHEDOCS_DATA) { - return READTHEDOCS_DATA['commit'] - } else { - return "unknown-commit" - } -} - -},{}],5:[function(require,module,exports){ -module.exports = { - initEvents: initEvents -} - -display = require('./display') - -function initEvents() { - $(document).on("click", "a.sphinx-comment-open", function(event) { - event.preventDefault(); - display.displayComments($(this).attr('id').substring('comment-open-'.length)); - }) - $(document).on("click", "a.sphinx-comment-close", function(event) { - event.preventDefault(); - display.closeComments($(this).attr('id').substring('comment-close-'.length)); - }) - - $(document).on("submit", ".comment-reply-form", function(event) { - event.preventDefault(); - comm.addComment($(this)); - }) - - $(document).on("submit", ".comment-attach-form", function(event) { - event.preventDefault(); - comm.attachComment($(this)); - }) -} - - -},{"./display":3}],6:[function(require,module,exports){ -var baseURL = "{{ websupport2_base_url }}"; -var staticURL = "{{ websupport2_static_url }}"; - -// Template rendering failed -if (baseURL.lastIndexOf("{{", 0) === 0) { - var rootURL = "http://localhost:8000"; - var baseURL = "http://localhost:8000/websupport"; - var staticURL = "http://localhost:8000/static"; -} - -var metadata = {} - -var opts = { - // Dynamic Content - processVoteURL: baseURL + '/_process_vote', - addCommentURL: rootURL + '/api/v2/comments/', - attachCommentURL: baseURL + '/_attach_comment', - getCommentsURL: rootURL + '/api/v2/comments/', - acceptCommentURL: baseURL + '/_accept_comment', - deleteCommentURL: baseURL + '/_delete_comment', - metadataURL: baseURL + '/_get_metadata', - optionsURL: baseURL + '/_get_options', - - // Static Content - commentImage: staticURL + '/_static/comment.png', - closeCommentImage: staticURL + '/_static/comment-close.png', - loadingImage: staticURL + '/_static/ajax-loader.gif', - commentBrightImage: staticURL + '/_static/comment-bright.png', - upArrow: staticURL + '/_static/up.png', - downArrow: staticURL + '/_static/down.png', - upArrowPressed: staticURL + '/_static/up-pressed.png', - downArrowPressed: staticURL + '/_static/down-pressed.png', - - voting: false, - moderator: false -}; - - -module.exports = { - metadata: metadata, - opts: opts, - staticURL: staticURL, - baseURL: baseURL -} - - -},{}]},{},[1]); diff --git a/package.json b/package.json index d417545aa0c..c7ad1756b51 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "readthedocs", - "version": "10.0.0", + "version": "10.1.0", "description": "Read the Docs build dependencies", "author": "Read the Docs, Inc ", "scripts": { diff --git a/readthedocs/__init__.py b/readthedocs/__init__.py index 147694f8d66..f7ad2928b39 100644 --- a/readthedocs/__init__.py +++ b/readthedocs/__init__.py @@ -1,4 +1,4 @@ """Read the Docs.""" -__version__ = "10.0.0" +__version__ = "10.1.0" diff --git a/readthedocs/api/v2/serializers.py b/readthedocs/api/v2/serializers.py index 521a2e7acf4..59d09fc7530 100644 --- a/readthedocs/api/v2/serializers.py +++ b/readthedocs/api/v2/serializers.py @@ -17,20 +17,21 @@ class ProjectSerializer(serializers.ModelSerializer): class Meta: model = Project fields = ( - 'id', - 'name', - 'slug', - 'description', - 'language', - 'programming_language', - 'repo', - 'repo_type', - 'default_version', - 'default_branch', - 'documentation_type', - 'users', - 'canonical_url', - 'urlconf', + "id", + "name", + "slug", + "description", + "language", + "programming_language", + "repo", + "repo_type", + "default_version", + "default_branch", + "documentation_type", + "users", + "canonical_url", + "urlconf", + "custom_prefix", ) diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index a9cadd101e8..449347e2160 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -217,8 +217,6 @@ def get_config_params(self): ) data = { - "html_theme": "sphinx_rtd_theme", - "html_theme_import": "sphinx_rtd_theme", "current_version": self.version.verbose_name, "project": self.project, "version": self.version, @@ -257,9 +255,6 @@ def get_config_params(self): "docsearch_disabled": self.project.has_feature( Feature.DISABLE_SERVER_SIDE_SEARCH ), - "skip_html_theme_path": self.project.has_feature( - Feature.SKIP_SPHINX_HTML_THEME_PATH - ), } finalize_sphinx_context_data.send( diff --git a/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl b/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl index 2884c604840..f59c0d58c32 100644 --- a/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl +++ b/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl @@ -48,54 +48,6 @@ if not 'html_static_path' in globals(): if os.path.exists('_static'): html_static_path.append('_static') -# Add RTD Theme only if they aren't overriding it already -using_rtd_theme = ( - ( - 'html_theme' in globals() and - html_theme in ['default'] and - # Allow people to bail with a hack of having an html_style - 'html_style' not in globals() - ) or 'html_theme' not in globals() -) -if using_rtd_theme: - html_theme = '{{ html_theme }}' - html_style = None - html_theme_options = {} - -{% comment %} -# Legacy behavior for html_theme_path: -# It is suspected that old builds with sphinx_rtd_theme required an extra -# definition of html_theme_path in order to work. -# This behavior is seen documented for old releases of sphinx_rtd_theme. -# An example of old instructions: -# https://github.com/readthedocs/sphinx_rtd_theme/blob/abd951a9cd98851269b8b5f5e59b1b4d29b1416c/README.rst -# Discussion of issue: -# https://github.com/readthedocs/readthedocs.org/pull/9654 -# -# We need to isolate the old legacy behavior because it causes Sphinx -# to skip calling the theme's setup(app) so its initialization never happens. -{% endcomment %} -# This following legacy behavior will gradually be sliced out until its deprecated and removed. -# Skipped for Sphinx 6+ -# Skipped by internal Feature flag SKIP_SPHINX_HTML_THEME_PATH -# Skipped by all new projects since SKIP_SPHINX_HTML_THEME_PATH's introduction (jan 2023) -if ( - using_rtd_theme - and version_info < (6,0) - and not {{ skip_html_theme_path|yesno:"True,False" }} - ): - theme = importlib.import_module('{{ html_theme_import }}') - if 'html_theme_path' in globals(): - html_theme_path.append(theme.get_html_theme_path()) - else: - html_theme_path = [theme.get_html_theme_path()] - -# Define websupport2_base_url and websupport2_static_url -if globals().get('websupport2_base_url', False): - websupport2_base_url = '{{ api_host }}/websupport' - websupport2_static_url = '{{ settings.STATIC_URL }}' - - #Add project information to the template context. context = { 'using_theme': using_rtd_theme, diff --git a/readthedocs/locale/ar/LC_MESSAGES/django.po b/readthedocs/locale/ar/LC_MESSAGES/django.po index 6ca15fe53db..0d152616a04 100644 --- a/readthedocs/locale/ar/LC_MESSAGES/django.po +++ b/readthedocs/locale/ar/LC_MESSAGES/django.po @@ -12,7 +12,7 @@ msgid "" msgstr "" "Project-Id-Version: readthedocs\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-08-14 22:29+0000\n" +"POT-Creation-Date: 2023-08-22 13:56+0000\n" "PO-Revision-Date: 2012-10-03 11:28+0000\n" "Last-Translator: Mustafa , 2020\n" "Language-Team: Arabic (http://app.transifex.com/readthedocs/readthedocs/" @@ -24,7 +24,7 @@ msgstr "" "Plural-Forms: nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 " "&& n%100<=10 ? 3 : n%100>=11 && n%100<=99 ? 4 : 5;\n" -#: analytics/models.py:69 builds/models.py:723 projects/models.py:1492 +#: analytics/models.py:69 builds/models.py:723 projects/models.py:1500 #: search/models.py:28 templates/base.html:262 msgid "Version" msgstr "الإصدار" @@ -145,7 +145,7 @@ msgstr "" msgid "Project with {slug_name}={value} is not valid as subproject" msgstr "" -#: api/v3/serializers.py:729 projects/forms.py:498 +#: api/v3/serializers.py:729 projects/forms.py:492 msgid "A subproject with this alias already exists" msgstr "" @@ -172,7 +172,7 @@ msgid "Log out" msgstr "" #: audit/models.py:91 organizations/views/private.py:145 -#: organizations/views/private.py:210 projects/views/private.py:467 +#: organizations/views/private.py:210 projects/views/private.py:447 msgid "Invitation sent" msgstr "" @@ -202,7 +202,7 @@ msgid "Username" msgstr "اسم المستخدم" #: audit/models.py:138 builds/models.py:110 builds/models.py:717 -#: projects/models.py:1486 redirects/models.py:56 +#: projects/models.py:1494 redirects/models.py:56 msgid "Project" msgstr "المشروع" @@ -441,7 +441,7 @@ msgstr "فعّال" msgid "Build successful" msgstr "" -#: builds/filters.py:28 projects/models.py:1610 +#: builds/filters.py:28 projects/models.py:1618 #: templates/builds/build_detail.html:143 msgid "Build failed" msgstr "" @@ -489,11 +489,11 @@ msgstr "" msgid "Invalid Python regular expression." msgstr "" -#: builds/models.py:98 projects/models.py:1573 projects/models.py:1741 +#: builds/models.py:98 projects/models.py:1581 projects/models.py:1749 msgid "created" msgstr "" -#: builds/models.py:103 projects/models.py:1578 +#: builds/models.py:103 projects/models.py:1586 msgid "modified" msgstr "" @@ -611,7 +611,7 @@ msgstr "خطأ" msgid "Exit code" msgstr "كود الخروج" -#: builds/models.py:773 projects/models.py:1503 +#: builds/models.py:773 projects/models.py:1511 msgid "Commit" msgstr "تقديم" @@ -829,7 +829,7 @@ msgstr "" #: core/forms.py:55 #: organizations/templates/organizations/admin/organization_edit.html:15 -#: projects/forms.py:276 redirects/templates/redirects/redirect_form.html:80 +#: projects/forms.py:270 redirects/templates/redirects/redirect_form.html:80 #: templates/builds/regexautomationrule_form.html:28 #: templates/projects/environmentvariable_form.html:20 #: templates/projects/project_edit.html:22 @@ -1090,7 +1090,7 @@ msgid "Publication date" msgstr "تاريخ النشر" #: gold/models.py:29 organizations/models.py:34 organizations/models.py:220 -#: organizations/models.py:294 projects/models.py:138 projects/models.py:1505 +#: organizations/models.py:294 projects/models.py:138 projects/models.py:1513 #: subscriptions/models.py:23 subscriptions/models.py:89 #: subscriptions/models.py:144 msgid "Modified date" @@ -1374,7 +1374,7 @@ msgstr "" #: oauth/models.py:33 oauth/models.py:126 organizations/filters.py:22 #: organizations/filters.py:28 organizations/models.py:50 #: organizations/models.py:243 projects/filters.py:42 projects/filters.py:107 -#: projects/models.py:147 projects/models.py:1497 subscriptions/models.py:26 +#: projects/models.py:147 projects/models.py:1505 subscriptions/models.py:26 msgid "Name" msgstr "الاسم" @@ -1536,11 +1536,11 @@ msgstr "" msgid "Organization %(name)s already exists" msgstr "" -#: organizations/forms.py:133 organizations/forms.py:218 projects/forms.py:507 +#: organizations/forms.py:133 organizations/forms.py:218 projects/forms.py:501 msgid "Email address or username" msgstr "" -#: organizations/forms.py:149 organizations/forms.py:253 projects/forms.py:522 +#: organizations/forms.py:149 organizations/forms.py:253 projects/forms.py:516 #, python-format msgid "User %(username)s does not exist" msgstr "" @@ -2061,7 +2061,7 @@ msgstr "Mercurial" msgid "Bazaar" msgstr "Bazaar" -#: projects/constants.py:99 projects/models.py:2161 +#: projects/constants.py:99 projects/models.py:2162 msgid "Public" msgstr "للعامة" @@ -2185,84 +2185,80 @@ msgstr "" msgid "Visibility" msgstr "" -#: projects/forms.py:102 -msgid "Edit advanced project options" -msgstr "" - -#: projects/forms.py:125 +#: projects/forms.py:119 msgid "Invalid project name, a project already exists with that name" msgstr "" -#: projects/forms.py:129 +#: projects/forms.py:123 msgid "Invalid project name" msgstr "" -#: projects/forms.py:147 +#: projects/forms.py:141 msgid "Repository invalid" msgstr "" -#: projects/forms.py:188 +#: projects/forms.py:182 msgid "Length of each tag must be less than or equal to 100 characters." msgstr "" -#: projects/forms.py:266 +#: projects/forms.py:260 msgid "Global settings" msgstr "" -#: projects/forms.py:270 +#: projects/forms.py:264 msgid "Default settings" msgstr "" -#: projects/forms.py:314 +#: projects/forms.py:308 msgid "To build from pull requests you need a " msgstr "" -#: projects/forms.py:325 +#: projects/forms.py:319 msgid "" "To build from pull requests your repository's webhook needs to send pull " "request events. " msgstr "" -#: projects/forms.py:373 +#: projects/forms.py:367 msgid "" "Your configuration file is invalid, make sure it contains conf.py in it." msgstr "" -#: projects/forms.py:435 +#: projects/forms.py:429 #, python-brace-format msgid "There is already a \"{lang}\" translation for the {proj} project." msgstr "" -#: projects/forms.py:526 +#: projects/forms.py:520 #, python-format msgid "User %(username)s is already a maintainer" msgstr "" -#: projects/forms.py:608 +#: projects/forms.py:602 msgid "The payload must be a valid JSON object." msgstr "" -#: projects/forms.py:796 +#: projects/forms.py:790 msgid "Only one domain can be canonical at a time." msgstr "" -#: projects/forms.py:900 +#: projects/forms.py:894 msgid "Variable name can't start with __ (double underscore)" msgstr "" -#: projects/forms.py:904 +#: projects/forms.py:898 msgid "Variable name can't start with READTHEDOCS" msgstr "" -#: projects/forms.py:909 +#: projects/forms.py:903 msgid "There is already a variable with this name for this project" msgstr "" -#: projects/forms.py:914 +#: projects/forms.py:908 msgid "Variable name can't contain spaces" msgstr "" -#: projects/forms.py:918 +#: projects/forms.py:912 msgid "Only letters, numbers and underscore are allowed" msgstr "" @@ -2500,7 +2496,7 @@ msgstr "" msgid "Create a PDF version of your documentation with each build." msgstr "" -#: projects/models.py:383 projects/models.py:1502 +#: projects/models.py:383 projects/models.py:1510 msgid "Path" msgstr "المسار" @@ -2615,274 +2611,270 @@ msgstr "" msgid "Model must have slug" msgstr "" -#: projects/models.py:1373 +#: projects/models.py:1381 msgid "Subproject nesting is not supported" msgstr "" -#: projects/models.py:1504 +#: projects/models.py:1512 msgid "Build id" msgstr "" -#: projects/models.py:1507 +#: projects/models.py:1515 msgid "Page search rank" msgstr "" -#: projects/models.py:1512 +#: projects/models.py:1520 msgid "Ignore this file from operations like indexing" msgstr "" -#: projects/models.py:1608 +#: projects/models.py:1616 msgid "Build triggered" msgstr "" -#: projects/models.py:1609 +#: projects/models.py:1617 msgid "Build passed" msgstr "" -#: projects/models.py:1626 +#: projects/models.py:1634 msgid "URL" msgstr "" -#: projects/models.py:1628 +#: projects/models.py:1636 msgid "URL to send the webhook to" msgstr "" -#: projects/models.py:1631 +#: projects/models.py:1639 msgid "Secret used to sign the payload of the webhook" msgstr "" -#: projects/models.py:1639 +#: projects/models.py:1647 msgid "Events to subscribe" msgstr "" -#: projects/models.py:1642 +#: projects/models.py:1650 msgid "JSON payload" msgstr "" -#: projects/models.py:1644 +#: projects/models.py:1652 msgid "" "JSON payload to send to the webhook. Check the docs for available substitutions." msgstr "" -#: projects/models.py:1752 +#: projects/models.py:1760 msgid "Domain" msgstr "النطاق" -#: projects/models.py:1759 +#: projects/models.py:1767 msgid "This domain was auto-created" msgstr "" -#: projects/models.py:1763 +#: projects/models.py:1771 msgid "This domain is a CNAME for the project" msgstr "" -#: projects/models.py:1768 +#: projects/models.py:1776 msgid "This domain is the primary one where the documentation is served from" msgstr "" -#: projects/models.py:1772 +#: projects/models.py:1780 msgid "Use HTTPS" msgstr "" -#: projects/models.py:1774 +#: projects/models.py:1782 msgid "Always use HTTPS for this domain" msgstr "" -#: projects/models.py:1778 +#: projects/models.py:1786 msgid "Number of times this domain has been hit" msgstr "" -#: projects/models.py:1783 templates/projects/domain_form.html:49 +#: projects/models.py:1791 templates/projects/domain_form.html:49 msgid "SSL certificate status" msgstr "" -#: projects/models.py:1792 +#: projects/models.py:1800 msgid "Skip validation process." msgstr "" -#: projects/models.py:1798 +#: projects/models.py:1806 msgid "Start date of the validation process." msgstr "" -#: projects/models.py:1809 +#: projects/models.py:1817 msgid "Set a custom max-age (eg. 31536000) for the HSTS header" msgstr "" -#: projects/models.py:1813 +#: projects/models.py:1821 msgid "" "If hsts_max_age > 0, set the includeSubDomains flag with the HSTS header" msgstr "" -#: projects/models.py:1817 +#: projects/models.py:1825 msgid "If hsts_max_age > 0, set the preload flag with the HSTS header" msgstr "" -#: projects/models.py:1964 -msgid "Sphinx: Do not define html_theme_path on Sphinx < 6.0" -msgstr "" - -#: projects/models.py:1969 +#: projects/models.py:1970 msgid "MkDocs: Use Read the Docs theme for MkDocs as default theme" msgstr "" -#: projects/models.py:1973 +#: projects/models.py:1974 msgid "Build: Do not shallow clone when cloning git repos" msgstr "" -#: projects/models.py:1977 +#: projects/models.py:1978 msgid "Build: Try alternative method of posting large data" msgstr "" -#: projects/models.py:1981 +#: projects/models.py:1982 msgid "Conda: Upgrade conda before creating the environment" msgstr "" -#: projects/models.py:1985 +#: projects/models.py:1986 msgid "Conda: Append Read the Docs core requirements to environment.yml file" msgstr "" -#: projects/models.py:1990 +#: projects/models.py:1991 msgid "" "Sphinx: Pass all versions (including private) into the html context when " "building with Sphinx" msgstr "" -#: projects/models.py:1997 +#: projects/models.py:1998 msgid "" "Proxito: CDN support for a project's public versions when privacy levels are " "enabled." msgstr "" -#: projects/models.py:2003 +#: projects/models.py:2004 msgid "Proxito: Record 404s page views." msgstr "" -#: projects/models.py:2007 +#: projects/models.py:2008 msgid "Proxito: Allow forced redirects." msgstr "" -#: projects/models.py:2011 +#: projects/models.py:2012 msgid "Proxito: Disable all page views" msgstr "" -#: projects/models.py:2015 +#: projects/models.py:2016 msgid "Proxito: Allow usage of the X-RTD-Slug header" msgstr "" -#: projects/models.py:2020 +#: projects/models.py:2021 msgid "" "Proxito: Use new unresolver implementation for serving documentation files." msgstr "" -#: projects/models.py:2025 +#: projects/models.py:2027 +msgid "" +"Proxito: Use proxied APIs (/_/*) with the custom prefix if the project has " +"one (Project.custom_prefix)." +msgstr "" + +#: projects/models.py:2032 msgid "Dashboard: Allow project to use the version warning banner." msgstr "" -#: projects/models.py:2031 +#: projects/models.py:2038 msgid "Webhook: Skip syncing branches" msgstr "" -#: projects/models.py:2035 +#: projects/models.py:2042 msgid "Webhook: Skip syncing tags" msgstr "" -#: projects/models.py:2039 +#: projects/models.py:2046 msgid "Webhook: Skip sync versions task" msgstr "" -#: projects/models.py:2043 +#: projects/models.py:2050 msgid "Build: Always run pip install --upgrade" msgstr "" -#: projects/models.py:2044 +#: projects/models.py:2051 msgid "Build: Use new pip resolver" msgstr "" -#: projects/models.py:2047 +#: projects/models.py:2054 msgid "Build: Don't install the latest version of pip" msgstr "" -#: projects/models.py:2049 +#: projects/models.py:2056 msgid "Sphinx: Use latest version of Sphinx" msgstr "" -#: projects/models.py:2052 +#: projects/models.py:2059 msgid "MkDOcs: Install mkdocs 0.17.3 by default" msgstr "" -#: projects/models.py:2056 +#: projects/models.py:2063 msgid "Sphinx: Use latest version of the Read the Docs Sphinx extension" msgstr "" -#: projects/models.py:2061 +#: projects/models.py:2068 msgid "" "Build: Install all the latest versions of Read the Docs core requirements" msgstr "" -#: projects/models.py:2068 +#: projects/models.py:2075 msgid "Search: Disable server side search" msgstr "" -#: projects/models.py:2072 +#: projects/models.py:2079 msgid "Search: Enable server side search for MkDocs projects" msgstr "" -#: projects/models.py:2076 +#: projects/models.py:2083 msgid "Search: Default to fuzzy search for simple search queries" msgstr "" -#: projects/models.py:2081 +#: projects/models.py:2088 msgid "" "Search: Index content directly from html files instead or relying in other " "sources" msgstr "" -#: projects/models.py:2088 -msgid "" -"Build: Use simplified and optimized git clone + git fetch + git checkout " -"patterns" -msgstr "" - -#: projects/models.py:2094 +#: projects/models.py:2095 msgid "" "Proxito: Inject 'readthedocs-addons.js' as