diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 8a2275daafe..79f06500ee2 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -4789,7 +4789,7 @@ Version 2.1.5 * `@stsewd `__: Move project description to the top (`#3510 `__) * `@RichardLitt `__: Docs: Rename "Good First Bug" to "Good First Issue" (`#3505 `__) * `@stsewd `__: Fix regex for getting project and user (`#3501 `__) - * `@ericholscher `__: Check to make sure changes exist in BitBucket pushes (`#3480 `__) + * `@ericholscher `__: Check to make sure changes exist in Bitbucket pushes (`#3480 `__) * `@andrewgodwin `__: "stable" appearing to track future release branches (`#3268 `__) * `@cdeil `__: No module named pip in conda build (`#2827 `__) * `@Yaseenh `__: building project does not generate new pdf with changes in it (`#2758 `__) @@ -4806,7 +4806,7 @@ Version 2.1.4 * `@davidfischer `__: Small formatting change to the Alabaster footer (`#3491 `__) * `@matsen `__: Fixing "resetting" misspelling. (`#3487 `__) * `@ericholscher `__: Add David to dev team listing (`#3485 `__) - * `@ericholscher `__: Check to make sure changes exist in BitBucket pushes (`#3480 `__) + * `@ericholscher `__: Check to make sure changes exist in Bitbucket pushes (`#3480 `__) * `@ericholscher `__: Use semvar for readthedocs-build to make bumping easier (`#3475 `__) * `@davidfischer `__: Add programming languages (`#3471 `__) * `@humitos `__: Remove TEMPLATE_LOADERS since it's the default (`#3469 `__) diff --git a/docs/_static/js/expand_tabs.js b/docs/_static/js/expand_tabs.js index f825dce4d5e..8f874455d16 100644 --- a/docs/_static/js/expand_tabs.js +++ b/docs/_static/js/expand_tabs.js @@ -1,9 +1,13 @@ /* * Expands a specific tab of sphinx-tabs. * Usage: - * - docs.readthedocs.io/?tab=Name - * - docs.readthedocs.io/?tab=Name#section - * Where 'Name' is the title of the tab (case sensitive). + * 1) docs.readthedocs.io/?tab=Name + * 2) docs.readthedocs.io/?tab=Name#section + * 3) docs.readthedocs.io/page#sphinx-label + * In 1) and 2), 'Name' is the title of the tab (case sensitive). + * + * In 3), you need to add a sphinx reference inside the tab. + * It mimics how sections are referenced and can be refactored. */ $( document ).ready(function() { const urlParams = new URLSearchParams(window.location.search); @@ -14,4 +18,20 @@ $( document ).ready(function() { tab.click(); } } + + // Uses a hash referencing a Sphinx label from the URL page#sphinx-label + var hash = window.location.hash.substr(1); + hash = hash.replace(/[^0-9a-z\-_]/gi, ''); + // If the hash is inside a tab panel + var tab_with_reference = $(".sphinx-tabs-panel #" + hash).parents(".sphinx-tabs-panel"); + + if (tab_with_reference.length > 0) { + // Use the panel's ID to guess the tab's ID + var panel_id = tab_with_reference.first().attr("id"); + var tab_id = panel_id.replace("panel-", "tab-"); + // Invoke the tab buttons click() method to display it + $("button#" + tab_id).click(); + // Scroll the tab widget into view + $('html, body').animate({ scrollTop: tab_with_reference.parents(".sphinx-tabs").first().offset().top}, 1000); + } }); diff --git a/docs/conf.py b/docs/conf.py index e94fb416398..61664de69a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,6 +21,7 @@ "multiproject", "sphinx.ext.autosectionlabel", "sphinx.ext.autodoc", + "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinxcontrib.httpdomain", "sphinxcontrib.video", @@ -58,8 +59,9 @@ copyright = "Read the Docs, Inc & contributors" version = "9.5.0" release = version -exclude_patterns = ["_build", "shared"] +exclude_patterns = ["_build", "shared", "_includes"] default_role = "obj" +intersphinx_cache_limit = 14 # cache for 2 weeks intersphinx_timeout = 3 # 3 seconds timeout intersphinx_mapping = { "python": ("https://docs.python.org/3.10/", None), @@ -147,8 +149,11 @@ hoverxref_domains = ["py"] hoverxref_roles = [ "option", - "doc", # Documentation pages - "term", # Glossary terms + # Documentation pages + # Not supported yet: https://github.com/readthedocs/sphinx-hoverxref/issues/18 + "doc", + # Glossary terms + "term", ] hoverxref_role_types = { "mod": "modal", # for Python Sphinx Domain @@ -201,5 +206,9 @@ r"https://readthedocs\.org/accounts/gold", ] +extlinks = { + "rtd-issue": ("https://github.com/readthedocs/readthedocs.org/issues/%s", "#%s"), +} + # Disable epub mimetype warnings suppress_warnings = ["epub.unknown_project_files"] diff --git a/docs/dev/install.rst b/docs/dev/install.rst index 67e47079d69..45d9e3c65df 100644 --- a/docs/dev/install.rst +++ b/docs/dev/install.rst @@ -196,7 +196,7 @@ Configuring connected accounts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These are optional steps to setup the :doc:`connected accounts ` -(GitHub, GitLab, and BitBucket) in your development environment. +(GitHub, GitLab, and Bitbucket) in your development environment. This will allow you to login to your local development instance using your GitHub, Bitbucket, or GitLab credentials and this makes the process of importing repositories easier. diff --git a/docs/user/_includes/organization-permissions.rst b/docs/user/_includes/organization-permissions.rst new file mode 100644 index 00000000000..2051a6abcef --- /dev/null +++ b/docs/user/_includes/organization-permissions.rst @@ -0,0 +1,13 @@ +Organization permissions +~~~~~~~~~~~~~~~~~~~~~~~~ + +To change your :doc:`Organization's ` settings, +you need to be an *owner* of that organization. + +You can validate your ownership of the Organization with these steps: + +* Navigate to :guilabel:`` > :guilabel:`Organizations` > :guilabel:`` +* Look at the :guilabel:`Owners` section on the right menu. + +If you'd like to modify this setting and are not an owner, +you can ask an existing organization owner to take the actions listed. diff --git a/docs/user/_static/images/guides/offline-formats.jpg b/docs/user/_static/images/guides/offline-formats.jpg new file mode 100644 index 00000000000..455801920b9 Binary files /dev/null and b/docs/user/_static/images/guides/offline-formats.jpg differ diff --git a/docs/user/_static/images/search-analytics-demo.png b/docs/user/_static/images/search-analytics-demo.png index 048849460b0..872d7eca025 100644 Binary files a/docs/user/_static/images/search-analytics-demo.png and b/docs/user/_static/images/search-analytics-demo.png differ diff --git a/docs/user/abandoned-projects.rst b/docs/user/abandoned-projects.rst index ac94186c1c8..fa6b79d1bc0 100644 --- a/docs/user/abandoned-projects.rst +++ b/docs/user/abandoned-projects.rst @@ -1,5 +1,5 @@ -Policy for Abandoned Projects -============================= +Abandoned projects policy +========================= This policy describes the process by which a Read the Docs project :term:`slug` may be changed. diff --git a/docs/user/about.rst b/docs/user/about/index.rst similarity index 54% rename from docs/user/about.rst rename to docs/user/about/index.rst index e715056410d..e36c5761070 100644 --- a/docs/user/about.rst +++ b/docs/user/about/index.rst @@ -4,7 +4,7 @@ About Read the Docs Read the Docs is a C Corporation registered in Oregon. Our bootstrapped company is owned and fully controlled by the founders, and fully funded by our customers and advertisers. -This allows us to **focus 100% on our users**. +This allows us to **focus 100% on our users**. We have two main sources of revenue: @@ -25,3 +25,51 @@ This allows us to give back to the communities and projects that we support and We are proud about the way we manage our company and products, and are glad to have you on board with us in this :doc:`great documentation journey `. + +If you want to dive more into more specific information and our policies, +we've brought most of the most important ones below. + +⏩ :doc:`/commercial/index` + Learn more about how our company provides paid solutions + +⏩ :doc:`/reference/policies` + Policies and legal documents used by |org_brand| and |com_brand|. + +⏩ :doc:`/advertising/index` + Information about how advertisement in Read the Docs + +⏩ :doc:`/story` + A brief throwback to how we were founded + +⏩ :doc:`/sponsors` + Read about who currently sponsors Read the Docs and who sponsored us in the past. + +⏩ :doc:`/open-source-philosophy` + Our philosophy is anchored in open source. + +⏩ :doc:`/team` + How we work and who we are. + +⏩ :doc:`/support` + Read this before asking for help: How to get support and where. + +⏩ :doc:`/glossary` + A useful index of terms used in our docs + +.. seealso:: + + `Our website `__ + Our primary website has general-purpose information about Read the Docs like pricing and feature overviews. + +.. toctree:: + :hidden: + + /commercial/index + /reference/policies + /advertising/index + /story + /sponsors + /open-source-philosophy + /team + /support + /glossary diff --git a/docs/user/analytics.rst b/docs/user/analytics.rst index bc20b83962e..95dfafa6bc1 100644 --- a/docs/user/analytics.rst +++ b/docs/user/analytics.rst @@ -1,5 +1,8 @@ -Traffic Analytics -================= +How to use traffic analytics +============================ + +In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project. +You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project. Traffic Analytics lets you see *which* documents your users are reading. This allows you to understand how your documentation is being used, diff --git a/docs/user/api/index.rst b/docs/user/api/index.rst index bb2ea66d1d6..77a11fe6c76 100644 --- a/docs/user/api/index.rst +++ b/docs/user/api/index.rst @@ -12,4 +12,5 @@ from Read the Docs. v3 v2 + /server-side-search/api cross-site-requests diff --git a/docs/user/api/v3.rst b/docs/user/api/v3.rst index 942d891ef72..0bb7b937052 100644 --- a/docs/user/api/v3.rst +++ b/docs/user/api/v3.rst @@ -1654,7 +1654,7 @@ Remote Organizations ~~~~~~~~~~~~~~~~~~~~ Remote Organizations are the VCS organizations connected via -``GitHub``, ``GitLab`` and ``BitBucket``. +``GitHub``, ``GitLab`` and ``Bitbucket``. Remote Organization listing @@ -1717,7 +1717,7 @@ Remote Repositories ~~~~~~~~~~~~~~~~~~~ Remote Repositories are the importable repositories connected via -``GitHub``, ``GitLab`` and ``BitBucket``. +``GitHub``, ``GitLab`` and ``Bitbucket``. Remote Repository listing diff --git a/docs/user/automatic-redirects.rst b/docs/user/automatic-redirects.rst index d7b1599db4d..b5ec38d9e5c 100644 --- a/docs/user/automatic-redirects.rst +++ b/docs/user/automatic-redirects.rst @@ -1,60 +1,92 @@ -Automatic Redirects -=================== +.. old reference -Read the Docs supports redirecting certain URLs automatically. -This is an overview of the set of redirects that are fully supported and will work into the future. +.. _Automatic Redirects: -Redirecting to a Page ---------------------- +Best practices for linking to your documentation +================================================ -You can link to a specific page and have it redirect to your default version. -This is done with the ``/page/`` URL prefix. -You can reach this page by going to https://docs.readthedocs.io/page/automatic-redirects.html. +Once you start to publish documentation, +external sources will inevitably link to specific pages in your documentation. -This allows you to create links that are always up to date. +Sources of incoming links vary greatly depending on the type of documentation project that is published. +They can include everything from old emails to GitHub issues, wiki articles, software comments, PDF publications, or StackOverflow answers. +Most of these incoming sources are not in your control. -Another way to handle this is the ``latest`` version. -You can set your ``latest`` version to a specific version and just always link to ``latest``. -You can read more about this in our :doc:`versions ` page. +Read the Docs makes it easier to create and manage incoming links by redirecting certain URLs automatically +and giving you access to define your own redirects. -Root URL --------- +In this article, +we explain how our built-in redirects work and what we consider "best practice" for managing incoming links. -A link to the root of your documentation will redirect to the *default version*, -as set in your project settings. -For example:: +.. seealso:: - docs.readthedocs.io -> docs.readthedocs.io/en/latest/ - www.pip-installer.org -> www.pip-installer.org/en/latest/ + :doc:`/versions` + Read more about how to handle versioned documentation and URL structures. -This only works for the root URL, not for internal pages. It's designed to redirect people from ``http://pip.readthedocs.io/`` to the default version of your documentation, since serving up a 404 here would be a pretty terrible user experience. (If your "develop" branch was designated as your default version, then it would redirect to ``http://pip.readthedocs.io/en/develop``.) But, it's not a universal redirecting solution. So, for example, a link to an internal page like ``http://pip.readthedocs.io/usage.html`` doesn't redirect to ``http://pip.readthedocs.io/en/latest/usage.html``. + :doc:`/user-defined-redirects` + Overview of all the redirect features available on Read the Docs. + Many of the redirect features are useful either for building external links or handling requests to old URLs. -The reasoning behind this is that RTD organizes the URLs for docs so that multiple translations and multiple versions of your docs can be organized logically and consistently for all projects that RTD hosts. For the way that RTD views docs, ``http://pip.readthedocs.io/en/latest/`` is the root directory for your default documentation in English, not ``http://pip.readthedocs.io/``. Just like ``http://pip.readthedocs.io/en/develop/`` is the root for your development documentation in English. + :doc:`/guides/redirects` + How to add a user-defined redirect, step-by-step. + Useful if your content changes location! -Among all the multiple versions of docs, you can choose which is the "default" version for RTD to display, which usually corresponds to the git branch of the most recent official release from your project. -rtfd.io -~~~~~~~~ +Best practice: "permalink" your pages +------------------------------------- -Links to rtfd.io are treated the same way as above. -They redirect the root URL to the default version of the project. -They are intended to be easy and short for people to type. +You might be familiar with the concept of `permalinks`_ from blogging. +The idea is that a blog post receives a unique link as soon as it's published and that the link does not change afterward. +Incoming sources can reference the blog post even though the blog changes structure or the post title changes. -You can reach these docs at https://docs.rtfd.io. +When creating an external link to a specific documentation page, +chances are that the page is moved as the documentation changes over time. -Supported Top-Level Redirects ------------------------------ +How should a permalink look for a documentation project? +Firstly, you should know that a *permalink* does not really exist in documentation but it is the result of careful actions to avoid breaking incoming links. -.. note:: These "implicit" redirects are supported for legacy reasons. - We will not be adding support for any more magic redirects. - If you want additional redirects, - they should live at a prefix like `Redirecting to a Page`_ +As a documentation owner, +you most likely want users clicking on incoming links to see the latest version of the page. -The main challenge of URL routing in Read the Docs is handling redirects correctly. Both in the interest of redirecting older URLs that are now obsolete, and in the interest of handling "logical-looking" URLs (leaving out the lang_slug or version_slug shouldn't result in a 404), the following redirects are supported:: +.. _permalinks: https://en.wikipedia.org/wiki/Permalink - / -> /en/latest/ - /en/ -> /en/latest/ - /latest/ -> /en/latest/ +Good practice ✅ +~~~~~~~~~~~~~~~~ -The language redirect will work for any of the defined ``LANGUAGE_CODES`` we support. -The version redirect will work for supported versions. +* Use `page redirects `_ if you are linking to the page in the :term:`default version` of the default language. This allows links to continue working even if those defaults change. +* If you move a page that likely has incoming references, :doc:`create a custom redirect rule `. +* Links to other Sphinx projects should use :doc:`intersphinx `. +* Use minimal filenames that don't require renaming often. +* When possible, + keep original file names rather than going for low-impact URL renaming. + Renaming an article's title is great for the reader and great for SEO, + but this does not have to involve the URL. +* Establish your understanding of the *latest* and *:term:`default version`* of your documentation at the beginning. Changing their meaning is very disruptive to incoming links. +* Keep development versions :ref:`hidden ` so people do not find them on search engines by mistake. + This is the best way to ensure that nobody links to URLs that are intended for development purposes. +* Use a :ref:`version warning ` to ensure the reader is aware in case they are reading an old (archived) version. + +.. tip:: + + Using Sphinx? + If you are using ``:ref:`` for :doc:`cross-referencing `, you may add as many reference labels to a headline as you need, + keeping old reference labels. This will make refactoring documentation easier and avoid that external projects + referencing your documentation through :doc:`intersphinx ` break. + +Questionable practice 🟡 +~~~~~~~~~~~~~~~~~~~~~~~~ + +* Avoid using specific versions in links unless users need that exact version. + Versions get outdated. +* Avoid using a public ``latest`` for development versions and do not make your *default version* a development branch. + Publishing development branches can mean that users are reading instructions for unreleased software or draft documentation. + +.. tip:: + + 404 pages are also okay! + If documentation pages have been removed or moved, + it can make the maintainer of the referring website aware that they need to update their link. + Users will be aware that the documentation **project** still exists but has changed. + + The default Read the Docs 404 page is designed to be helpful, + but you can also design your own, see :ref:`hosting:Custom Not Found (404) Pages`. diff --git a/docs/user/automation-rules.rst b/docs/user/automation-rules.rst index 66ce2896ac2..5245abbdedc 100644 --- a/docs/user/automation-rules.rst +++ b/docs/user/automation-rules.rst @@ -1,42 +1,55 @@ -Automation Rules +Automation rules ================ -Automation rules allow project maintainers to automate actions on new branches and tags on repositories. +Automation rules allow project maintainers to automate actions on new branches and tags in Git repositories. +If you are familiar with :term:`GitOps`, +this might seem familiar. +The goal of automation rules is to be able to control versioning through your Git repository +and avoid duplicating these efforts on Read the Docs. -Creating an automation rule ---------------------------- +.. seealso:: -#. Go to your project dashboard -#. Click :guilabel:`Admin` > :guilabel:`Automation Rules` -#. Click on :guilabel:`Add Rule` -#. Fill in the fields -#. Click :guilabel:`Save` + :doc:`/guides/automation-rules` + A practical guide to managing automated versioning of your documentation. -How do they work? ------------------ + :doc:`/versions` + General explanation of how versioning works on Read the Docs + +How automation rules work +------------------------- When a new tag or branch is pushed to your repository, -Read the Docs creates a new version. +Read the Docs receives a webhook. +We then create a new Read the Docs *version* that matches your new Git *tag or branch*. -All rules are evaluated for this version, in the order they are listed. -If the version matches the version type and the pattern in the rule, -the specified action is performed on that version. +All automation rules are evaluated for this version, +in the order they are listed. +If the version **matches** the version type and the pattern in the rule, +the specified **action** is performed on that version. + +.. _TODO: A diagram would be great here in the future, but probably too much for this refactor. .. note:: - Versions can match multiple rules, + Versions can match multiple automation rules, and all matching actions will be performed on the version. +Matching a version in Git +------------------------- + +We have a couple predefined ways to match against versions that are created, +and you can also define your own. + Predefined matches ------------------- +~~~~~~~~~~~~~~~~~~ -Automation rules support several predefined version matches: +Automation rules support two predefined version matches: - **Any version**: All new versions will match the rule. - **SemVer versions**: All new versions that follow `semantic versioning `__ will match the rule. -User defined matches --------------------- +Custom matches +~~~~~~~~~~~~~~ If none of the above predefined matches meet your use case, you can use a **Custom match**. @@ -44,53 +57,54 @@ you can use a **Custom match**. The custom match should be a valid `Python regular expression `__. Each new version will be tested against this regular expression. -Actions -------- +Actions for versions +-------------------- -When a rule matches a new version, the specified action is performed on that version. +When an automation rule matches a new version, +the specified action is performed on that version. Currently, the following actions are available: -- **Activate version**: Activates and builds the version. -- **Hide version**: Hides the version. If the version is not active, activates it and builds the version. - See :ref:`versions:Version States`. -- **Make version public**: Sets the version's privacy level to public. - See :ref:`versions:privacy levels`. -- **Make version private**: Sets the version's privacy level to private. - See :ref:`versions:privacy levels`. -- **Set version as default**: Sets the version as default, - i.e. the version of your project that `/` redirects to. - See more in :ref:`automatic-redirects:Root URL`. - It also activates and builds the version. -- **Delete version**: When a branch or tag is deleted from your repository, - Read the Docs will delete it *only if isn't active*. - This action allows you to delete *active* versions when a branch or tag is deleted from your repository. +Activate version + Activates and builds the version. - .. note:: +Hide version + Hides the version. If the version is not active, activates it and builds the version. + See :ref:`versions:Version states`. - The default version isn't deleted even if it matches a rule. - You can use the ``Set version as default`` action to change the default version - before deleting the current one. +Make version public + Sets the version's privacy level to public. + See :ref:`versions:Privacy levels`. +Make version private + Sets the version's privacy level to private. + See :ref:`versions:Privacy levels`. -.. note:: - - If your versions follow :pep:`440`, - Read the Docs activates and builds the version if it's greater than the current stable version. - The stable version is also automatically updated at the same time. - See more in :doc:`versions`. +Set version as default + Sets the version as the :term:`default version`. + It also activates and builds the version. + See :ref:`automatic-redirects:Root URL`. -Order ------ +Delete version + When a branch or tag is deleted from your repository, + Read the Docs will delete it *only if isn't active*. + This action allows you to delete *active* versions when a branch or tag is deleted from your repository. -The order your rules are listed in :guilabel:`Admin` > :guilabel:`Automation Rules` matters. -Each action will be performed in that order, -so first rules have a higher priority. +There are a couple caveats to these rules that are useful: -You can change the order using the up and down arrow buttons. +* The :term:`default version` isn't deleted even if it matches a rule. + You can use the ``Set version as default`` action to change the default version + before deleting the current one. +* If your versions follow :pep:`440`, + Read the Docs activates and builds the version if it's greater than the current stable version. + The stable version is also automatically updated at the same time. + See more in :doc:`versions`. -.. note:: +Order +----- - New rules are added at the end (lower priority). +When a new Read the Docs version is created, +all rules with a successful match will have their action triggered, +in the order they appear on the :guilabel:`Automation Rules` page. Examples -------- diff --git a/docs/user/badges.rst b/docs/user/badges.rst index afb7ea62df7..adfdaf8d538 100644 --- a/docs/user/badges.rst +++ b/docs/user/badges.rst @@ -21,6 +21,18 @@ An example of each is shown here: |green| |nbsp| |red| |nbsp| |yellow| +Automatically generated +----------------------- + +On the dashboard of a project, an example badge is displayed +together with code snippets for reStructuredText, Markdown, and HTML. + +Badges are generated on-demand for all Read the Docs projects, using the following URL syntax: + +.. code-block:: text + + https://readthedocs.org/projects//badge/?version=&style=
The rest is handled automatically
The next time your project is built,
its Canonical URLs use docs.example.com
Visit https://docs.example.com
Correct SSL Certificate
automatically used
Read the Docs knows
to serve your project
at docs.example.com
On your domain's DNS administration
Edit/add a DNS entry for docs.example.com
making it point to Read the Docs
On Read the Docs
Add docs.example.com as Custom Domain
Wait for DNS propagation.
Usually just a few minutes
 diff --git a/docs/user/img/oauth_github_dialog.png b/docs/user/img/oauth_github_dialog.png new file mode 100644 index 00000000000..04141b427b4 Binary files /dev/null and b/docs/user/img/oauth_github_dialog.png differ diff --git a/docs/user/img/screenshot_automation_rules_add.png b/docs/user/img/screenshot_automation_rules_add.png new file mode 100644 index 00000000000..62c863cfe05 Binary files /dev/null and b/docs/user/img/screenshot_automation_rules_add.png differ diff --git a/docs/user/img/screenshot_connected_services.png b/docs/user/img/screenshot_connected_services.png new file mode 100644 index 00000000000..ce8aaa8dc63 Binary files /dev/null and b/docs/user/img/screenshot_connected_services.png differ diff --git a/docs/user/img/screenshot_environment_variables.png b/docs/user/img/screenshot_environment_variables.png new file mode 100644 index 00000000000..fb678f3f9e6 Binary files /dev/null and b/docs/user/img/screenshot_environment_variables.png differ diff --git a/docs/user/img/screenshot_redirects.png b/docs/user/img/screenshot_redirects.png new file mode 100644 index 00000000000..f81f1aaba0f Binary files /dev/null and b/docs/user/img/screenshot_redirects.png differ diff --git a/docs/user/img/screenshot_redirects_preview.png b/docs/user/img/screenshot_redirects_preview.png new file mode 100644 index 00000000000..a31b4525b42 Binary files /dev/null and b/docs/user/img/screenshot_redirects_preview.png differ diff --git a/docs/user/img/screenshot_subprojects_list.png b/docs/user/img/screenshot_subprojects_list.png new file mode 100644 index 00000000000..e4c9c0ec027 Binary files /dev/null and b/docs/user/img/screenshot_subprojects_list.png differ diff --git a/docs/user/index.rst b/docs/user/index.rst index 58c7bcf0d01..385d3059aee 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -1,6 +1,55 @@ Read the Docs: Documentation Simplified ======================================= +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Tutorials 🚀 + + /tutorial/index + /intro/getting-started-with-sphinx + /intro/getting-started-with-mkdocs + /intro/import-guide + /examples + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Explanation 💡 + + /choosing-a-site + /integrations + /downloadable-documentation + /environment-variables + /subprojects + /localization + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: How-to guides 🪄 + + /guides/authors + /guides/administrators + /guides/developers + /guides/troubleshooting/index + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Reference 📚 + + /reference/features + /config-file/index + /builds + /build-customization + /server-side-search/syntax + /faq + /api/index + /changelog + /about/index + Developer Documentation 🔗 + .. meta:: :description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. @@ -29,7 +78,7 @@ Multiple versions |:card_index_dividers:| Open Source and User Focused |:heartbeat:| Our code is free and `open source `_. - :doc:`Our company ` is bootstrapped and 100% user focused. + :doc:`Our company ` is bootstrapped and 100% user focused. |org_brand| hosts documentation for over 100,000 large and small open source projects, in almost every human and computer language. @@ -37,7 +86,7 @@ Open Source and User Focused |:heartbeat:| .. _Read the docs: https://readthedocs.org/ -You can find out more about our all the :doc:`/features` in these pages. +You can find out more about our all the :doc:`features ` in these pages. First steps ----------- @@ -57,19 +106,6 @@ to help you create fantastic documentation for your project. * **Importing your existing documentation**: :doc:`Import guide ` - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: First steps - - /tutorial/index - /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs - /intro/import-guide - /choosing-a-site - - Read the Docs feature overview ------------------------------ @@ -77,12 +113,9 @@ Learn more about configuring your automated documentation builds and some of the core features of Read the Docs. * **Overview of core features**: - :doc:`/features` | - :doc:`/integrations` | :doc:`/custom-domains` | :doc:`/versions` | :doc:`/downloadable-documentation` | - :doc:`/hosting` | :doc:`/server-side-search/index` | :doc:`/analytics` | :doc:`/pull-requests` | @@ -90,7 +123,7 @@ and some of the core features of Read the Docs. :doc:`/user-defined-redirects` | :doc:`/security-log` -* **Connecting with GitHub, BitBucket, or GitLab**: +* **Connecting with GitHub, Bitbucket, or GitLab**: :doc:`Connecting your VCS account ` * **Read the Docs build process**: @@ -98,40 +131,12 @@ and some of the core features of Read the Docs. :doc:`Build process ` | :doc:`Build customization ` | :doc:`/environment-variables` | + :doc:`/reference/environment-variables` | :doc:`/badges` * **Troubleshooting**: :doc:`/support` | - :doc:`Frequently asked questions ` - -.. toctree:: - :maxdepth: 1 - :hidden: - :caption: Features - - /features - /config-file/index - /integrations - /custom-domains - /versions - /downloadable-documentation - /hosting - /server-side-search/index - /analytics - /pull-requests - /build-notifications - /security-log - - /connected-accounts - - /builds - /build-customization - /build-troubleshooting - /environment-variables - /badges - - /support - /faq + :doc:`/faq` How-to Guides @@ -148,9 +153,13 @@ and how to write successful documentation. :doc:`More guides for authors ` * **For project administrators**: + :doc:`Connect Your Git Repository ` | + :doc:`Manage Custom Domains ` | :doc:`/guides/technical-docs-seo-guide` | :doc:`/guides/manage-translations-sphinx` | :doc:`/guides/private-submodules` | + :doc:`Configure Pull Request Builds ` | + :doc:`Use Traffic Analytics ` | :doc:`/guides/build-notifications` | :doc:`More guides for administrators ` @@ -160,19 +169,10 @@ and how to write successful documentation. :doc:`/guides/reproducible-builds` | :doc:`/guides/embedding-content` | :doc:`/guides/conda` | + :doc:`Use Traffic Analytics ` | :doc:`/guides/build-notifications` | :doc:`More guides for developers and designers ` -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: How-to Guides - - /guides/authors - /guides/administrators - /guides/developers - /science - /examples Advanced features of Read the Docs ---------------------------------- @@ -183,7 +183,7 @@ out of your documentation and Read the Docs. * **Advanced project configuration**: :doc:`subprojects` | - :doc:`Single version docs ` | + :doc:`Single version docs ` | :doc:`flyout-menu` | :doc:`feature-flags` @@ -202,27 +202,7 @@ out of your documentation and Read the Docs. * **Extending Read the Docs**: :doc:`REST API ` -.. toctree:: - :maxdepth: 2 - :hidden: - :glob: - :caption: Advanced features - - subprojects - single_version - flyout-menu - feature-flags - - localization - - user-defined-redirects - automatic-redirects - automation-rules - canonical-urls - - - api/index Read the Docs for Business -------------------------- @@ -236,14 +216,6 @@ Read the Docs has a commercial offering with improved support and additional fea :doc:`Sharing externally ` -.. toctree:: - :maxdepth: 1 - :hidden: - :caption: Read the Docs for Business - :glob: - - commercial/* - The Read the Docs project and organization ------------------------------------------ @@ -260,7 +232,7 @@ of Read the Docs and the larger software documentation ecosystem. * **The people and philosophy behind Read the Docs**: - :doc:`About Us ` | + :doc:`About Us ` | :doc:`Team ` | :doc:`Open source philosophy ` | :doc:`Our story ` @@ -276,31 +248,4 @@ of Read the Docs and the larger software documentation ecosystem. * **Getting involved with Read the Docs**: :doc:`/glossary` | - :doc:`/gsoc` | :doc:`Developer Documentation ` - - -.. toctree:: - :maxdepth: 1 - :hidden: - :caption: About Read the Docs - - security - dmca/index - abandoned-projects - unofficial-projects - changelog - - about - team - open-source-philosophy - story - - advertising/index - sponsors - - legal/index - - Developer Documentation - glossary - gsoc diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst index f04e86de1bc..c3b4dd3dba2 100644 --- a/docs/user/integrations.rst +++ b/docs/user/integrations.rst @@ -1,233 +1,72 @@ -VCS Integrations -================ +.. + Some points we want to cover in this article: + * Talk about the benefits of always up to date docs + * Discuss versioning in here, since it relies directly on Git? + * Have a small diagram that shows (You --push--> GitHub --webhook--> RTD --Build docs--> Deploy + (Perhaps reuse this: https://about.readthedocs.com/images/homepage.png) -Read the Docs provides integrations with several VCS providers to detect changes to your -documentation and versions, mainly using *webhooks*. -Integrations are configured with your repository provider, -such as GitHub, Bitbucket or GitLab, -and with each change to your repository, Read the Docs is notified. When we -receive an integration notification, we determine if the change is related to an -active version for your project, and if it is, a build is triggered for that -version. - -You'll find a list of configured integrations on your project's :guilabel:`Admin` -dashboard, under :guilabel:`Integrations`. You can select any of these integrations to -see the *integration detail page*. This page has additional configuration -details and a list of HTTP exchanges that have taken place for the integration, -including the Payload URL needed by the repository provider -such as GitHub, GitLab, or Bitbucket. - -Integration Creation --------------------- - -If you have :doc:`connected your Read the Docs account ` to GitHub, Bitbucket, or GitLab, -**an integration will be set up automatically for your repository**. However, if your -project was not imported through a connected account, you may need to -manually configure an integration for your project. - -To manually set up an integration, go to :guilabel:`Admin` > :guilabel:`Integrations` > :guilabel:`Add integration` -dashboard page and select the integration type you'd like to add. -After you have added the integration, you'll see a link to information about the integration. - -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. - -.. note:: - - If your account is connected to the provider, - we'll try to setup the integration automatically. - If something fails, you can still setup the integration manually. - -.. _webhook-integration-github: - -GitHub -~~~~~~ - -* Go to the :guilabel:`Settings` page for your **GitHub project** -* Click :guilabel:`Webhooks` > :guilabel:`Add webhook` -* For **Payload URL**, use the URL of the integration on your **Read the Docs project**, - found on the project's :guilabel:`Admin` > :guilabel:`Integrations` page. - You may need to prepend *https://* to the URL. -* For **Content type**, both *application/json* and - *application/x-www-form-urlencoded* work -* Leave the **Secrets** field blank -* Select **Let me select individual events**, - and mark **Branch or tag creation**, **Branch or tag deletion**, **Pull requests** and **Pushes** events -* Ensure **Active** is enabled; it is by default -* Finish by clicking **Add webhook**. You may be prompted to enter your GitHub password to confirm your action. - -You can verify if the webhook is working at the bottom of the GitHub page under **Recent Deliveries**. -If you see a Response 200, then the webhook is correctly configured. -For a 403 error, it's likely that the Payload URL is incorrect. - -.. note:: The webhook token, intended for the GitHub **Secret** field, is not yet implemented. - -.. _webhook-integration-bitbucket: - -Bitbucket -~~~~~~~~~ - -* Go to the :guilabel:`Settings` > :guilabel:`Webhooks` > :guilabel:`Add webhook` page for your project -* For **URL**, use the URL of the integration on Read the Docs, - found on the :guilabel:`Admin` > :guilabel:`Integrations` page -* Under **Triggers**, **Repository push** should be selected -* Finish by clicking **Save** - -.. _webhook-integration-gitlab: - -GitLab -~~~~~~ - -* Go to the :guilabel:`Settings` > :guilabel:`Webhooks` page for your GitLab project -* For **URL**, use the URL of the integration on **Read the Docs project**, - found on the :guilabel:`Admin` > :guilabel:`Integrations` page -* Leave the default **Push events** selected, - additionally mark **Tag push events** and **Merge request events**. -* Finish by clicking **Add Webhook** - -Gitea -~~~~~ - -These instructions apply to any Gitea instance. -.. warning:: +Continuous Documentation Deployment +=================================== - This isn't officially supported, but using the "GitHub webhook" is an effective workaround, - because Gitea uses the same payload as GitHub. The generic webhook is not compatible with Gitea. - See `issue #8364`_ for more details. Official support may be implemented in the future. +Read the Docs is a *Continuous Documentation Deployment* platform for your software project. +Every time you change something in your documentation, Read the Docs will detect your change and build your documentation. +This happens using *webhooks*. -On Read the Docs: - -* Manually create a "GitHub webhook" integration - (this will show a warning about the webhook not being correctly set up, - that will go away when the webhook is configured in Gitea) - -On your Gitea instance: - -* Go to the :guilabel:`Settings` > :guilabel:`Webhooks` page for your project on your Gitea instance -* Create a new webhook of type "Gitea" -* For **URL**, use the URL of the integration on Read the Docs, - found on the :guilabel:`Admin` > :guilabel:`Integrations` page -* Leave the default **HTTP Method** as POST -* For **Content type**, both *application/json* and - *application/x-www-form-urlencoded* work -* Leave the **Secret** field blank -* Select **Choose events**, - and mark **Branch or tag creation**, **Branch or tag deletion** and **Push** events -* Ensure **Active** is enabled; it is by default -* Finish by clicking **Add Webhook** -* Test the webhook with :guilabel:`Delivery test` - -Finally, on Read the Docs, check that the warnings have disappeared -and the delivery test triggered a build. - -.. _issue #8364: https://github.com/readthedocs/readthedocs.org/issues/8364 - -.. _webhook-integration-generic: - -Using the generic API integration ---------------------------------- - -For repositories that are not hosted with a supported provider, we also offer a -generic API endpoint for triggering project builds. Similar to webhook integrations, -this integration has a specific URL, which can be found on the project's **Integrations** dashboard page -(:guilabel:`Admin` > :guilabel:`Integrations`). - -Token authentication is required to use the generic endpoint, you will find this -token on the integration details page. The token should be passed in as a -request parameter, either as form data or as part of JSON data input. - -Parameters -~~~~~~~~~~ - -This endpoint accepts the following arguments during an HTTP POST: - -branches - The names of the branches to trigger builds for. This can either be an array - of branch name strings, or just a single branch name string. - - Default: **latest** - -token - The integration token found on the project's **Integrations** dashboard page - (:guilabel:`Admin` > :guilabel:`Integrations`). - -default_branch - This is the default branch of the repository - (ie. the one checked out when cloning the repository without arguments) - - *Optional* - -For example, the cURL command to build the ``dev`` branch, using the token -``1234``, would be:: - - curl -X POST -d "branches=dev" -d "token=1234" -d "default_branch=main" - https://readthedocs.org/api/v2/webhook/example-project/1/ - -A command like the one above could be called from a cron job or from a hook -inside Git_, Subversion_, Mercurial_, or Bazaar_. +The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider, +such as GitHub, Bitbucket or GitLab, +and with each change committed to your repository, Read the Docs is notified by the webhook. -.. _Git: http://www.kernel.org/pub/software/scm/git/docs/githooks.html -.. _Subversion: https://www.mikewest.org/2006/06/subversion-post-commit-hooks-101 -.. _Mercurial: http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html -.. _Bazaar: http://wiki.bazaar.canonical.com/BzrHooks +When we receive an integration notification, we determine if the change is related to an active version for your project. +If it is, a build is triggered for that version. -Authentication -~~~~~~~~~~~~~~ +Continuous Documentation for software projects +---------------------------------------------- -This endpoint requires authentication. If authenticating with an integration -token, a check will determine if the token is valid and matches the given -project. If instead an authenticated user is used to make this request, a check -will be performed to ensure the authenticated user is an owner of the project. +Documentation fits into any CI/CD pipeline through the idea and objectives of *Documentation as Code*. +A straight-forward method to achieve this is by maintaining documentation alongside the source code, +meaning that the documentation's life cycle is contained within the same Git repository as the source code. -Debugging webhooks ------------------- +When changes happen to the source code, changes should also happen to the documentation. +By managing these changes in the same life cycle, +you can benefit from **documentation and source code being part of the same code review process**. -If you are experiencing problems with an existing webhook, you may be able to -use the integration detail page to help debug the issue. Each project -integration, such as a webhook or the generic API endpoint, stores the HTTP -exchange that takes place between Read the Docs and the external source. You'll -find a list of these exchanges in any of the integration detail pages. +Having an automated and short feedback loop for your documentation allows you to +keep it updated with minimal effort. +This allows more iteration on documentation, +and increases overall value from the documentation you write. -Resyncing webhooks ------------------- +Continuous Documentation for all projects +----------------------------------------- -It might be necessary to re-establish a webhook if you are noticing problems. -To resync a webhook from Read the Docs, visit the integration detail page and -follow the directions for re-syncing your repository webhook. +All categories of documentation benefit from being *continuously* built and published through Read the Docs. -Payload validation ------------------- +If you are managing your documentation in Git, +you will be able to preview changes and see accepted changes published immediately using :doc:`/pull-requests`. -If your project was imported through a connected account, -we create a secret for every integration that offers a way to verify that a webhook request is legitimate. -Currently, `GitHub `__ and `GitLab `__ -offer a way to check this. +Automated versioning +-------------------- -Troubleshooting ---------------- +With Read the Docs' automated CI/CD pipeline, you will be able to fully align your project's **release cycle** with your documentation. +For instance, a new version of a software project can build and publish a new version of its documentation. -Webhook activation failed. Make sure you have the necessary permissions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Read the Docs is notified of all changes to your Git branches and tags. +When you release a new version for your project, +you are likely also adding a version tag to your Git repository. +These Git events can be configured to build and publish your documentation automatically with :doc:`/automation-rules`. +If you use a versioning schema, you can configure it as part of the automation process. -If you find this error, -make sure your user has permissions over the repository. -In case of GitHub, -check that you have granted access to the Read the Docs `OAuth App`_ to your organization. +Whether you choose to handle versioning automatically or with manual control is up to you. -.. _OAuth App: https://github.com/settings/applications +Read the Docs will store your version history and make it possible for users to visit archived versions of your documentation. +Your version setup is ultimately captured by the :term:`flyout menu`. -My project isn't automatically building -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your project isn't automatically building, you can check your integration on -Read the Docs to see the payload sent to our servers. If there is no recent -activity on your Read the Docs project webhook integration, then it's likely -that your VCS provider is not configured correctly. If there is payload -information on your Read the Docs project, you might need to verify that your -versions are configured to build correctly. +.. seealso:: -Either way, it may help to either resync your webhook integration (see -`Resyncing webhooks`_ for information on this process), or set up an entirely -new webhook integration. + :doc:`/guides/git-integrations` + Information on setting up your Git repository to make Read the Docs automatically build your documentation project. + :doc:`/automation-rules` + Information on setting up your Git repository to make Read the Docs automatically build your documentation project. + :doc:`/flyout-menu` + Discover the functionality of the Flyout menu and the ways that it can be customized. diff --git a/docs/user/intro/import-guide.rst b/docs/user/intro/import-guide.rst index cc8c0433679..c2c232a52f8 100644 --- a/docs/user/intro/import-guide.rst +++ b/docs/user/intro/import-guide.rst @@ -33,7 +33,8 @@ these properties, and then click **Next** to Manually import your docs ------------------------- -If you do not have a connected account, you will need to select **Import Manually** +If you have not :doc:`connected a Git provider account `, +you will need to select **Import Manually** and enter the information for your repository yourself. You will also need to manually configure the webhook for your repository as well. When importing your project, you will be asked for the repository URL, along with some other @@ -53,6 +54,11 @@ project on Read the Docs. Go to your project's :guilabel:`Admin` > :guilabel:`In configure a new webhook, or see :ref:`our steps for webhook creation ` for more information on this process. +.. seealso:: + + :doc:`/guides/git-integrations` + Once you have imported your git project, use this guide to manually set up basic and additional integration. + .. note:: The ``Admin`` page can be found at ``https://readthedocs.org/dashboard//edit/``. You can access all of the project settings from the admin page sidebar. diff --git a/docs/user/legal/index.rst b/docs/user/legal/index.rst deleted file mode 100644 index e43193e4547..00000000000 --- a/docs/user/legal/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -Legal Documents and Policies -============================ - -Here is some of the fine print used by |org_brand| and |com_brand|: - -.. toctree:: - :glob: - :hidden: - - /terms-of-service - /privacy-policy - security-policy - dpa/index - -:doc:`/terms-of-service` - The terms of service for using |org_brand| and |com_brand|. You may instead - have a master services agreement for your subscription if you have a custom - or enterprise contract. - -:doc:`/privacy-policy` - Our policy on collecting, storing, and protecting user and visitor data. - -:doc:`/legal/security-policy` - Our policies around application and infrastructure security. - -:doc:`/legal/dpa/index` - For GDPR and CCPA compliance, we provide a data processing addendum for - |com_brand| customers. diff --git a/docs/user/legal/security-policy.rst b/docs/user/legal/security-policy.rst index 0df5811419c..bfc85aa2502 100644 --- a/docs/user/legal/security-policy.rst +++ b/docs/user/legal/security-policy.rst @@ -1,4 +1,4 @@ -Security Policy +Security policy =============== Read the Docs adheres to the following security policies and procedures with @@ -73,3 +73,17 @@ Continuous integration Incident response Our engineering team is on a rotating on-call schedule to respond to security or availability incidents. + +Account security +---------------- + +* All traffic is encrypted in transit so your login is protected. +* Read the Docs stores only one-way hashes of all passwords. + Nobody at Read the Docs has access to your passwords. +* Account login is protected from brute force attacks with rate limiting. +* While most projects and docs on Read the Docs are public, + we treat your private repositories and private documentation as confidential + and Read the Docs employees may only view them + with your explicit permission in response to your support requests, + or when required for security purposes. +* You can read more about account privacy in our :doc:`/privacy-policy`. diff --git a/docs/user/localization.rst b/docs/user/localization.rst index 6c97c4caaec..897100fc95a 100644 --- a/docs/user/localization.rst +++ b/docs/user/localization.rst @@ -1,17 +1,26 @@ Localization of Documentation ============================= -.. note:: This feature only applies to Sphinx documentation. We are working to bring it to our other documentation backends. +In this article, we explain high-level approaches to internationalizing and localizing your documentation. -Read the Docs supports hosting your docs in multiple languages. -There are two different things that we support: +By default, Read the Docs assumes that your documentation is or *might become* multilingual one day. +The initial default language is English and +therefore you often see the initial build of your documentation published at ``/en/latest/``, +where the ``/en`` denotes that it's in English. +By having the ``en`` URL component present from the beginning, +you are ready for the eventuality that you would want a second language. -* A single project written in another language -* A project with translations into multiple languages +Read the Docs supports hosting your documentation in multiple languages. +Read below for the various approaches that we support. +.. contents:: + :local: -Single project in another language ----------------------------------- +Projects with one language +-------------------------- + +If your documentation isn't in English (the default), +you should indicate which language you have written it in. It is easy to set the *Language* of your project. On the project *Admin* page (or *Import* page), @@ -22,10 +31,13 @@ The language will be represented in the URL for your project. For example, a project that is in Spanish will have a default URL of ``/es/latest/`` instead of ``/en/latest/``. -.. note:: You must commit the ``.po`` files for Read the Docs to translate your documentation. +Projects with multiple translations (Sphinx-only) +------------------------------------------------- -Project with multiple translations ----------------------------------- +.. seealso:: + + :doc:`guides/manage-translations-sphinx` + Describes the whole process for a documentation with multiples languages in the same repository and how to keep the translations updated on time. This situation is a bit more complicated. To support this, @@ -44,7 +56,7 @@ This has the results of serving: * ``phpmyadmin`` at ``http://phpmyadmin.readthedocs.io/en/latest/`` * ``phpmyadmin-spanish`` at ``http://phpmyadmin.readthedocs.io/es/latest/`` -It also gets included in the Read the Docs flyout: +It also gets included in the Read the Docs :term:`flyout menu`: .. image:: /img/translation_bar.png @@ -57,4 +69,34 @@ It also gets included in the Read the Docs flyout: with same ``conf.py`` and ``.rst`` files, but each project must specify the language to build for those docs. -.. note:: You can read :doc:`guides/manage-translations-sphinx` to understand the whole process for a documentation with multiples languages in the same repository and how to keep the translations updated on time. +.. note:: You must commit the ``.po`` files for Read the Docs to translate your documentation. + + +Translation workflows +~~~~~~~~~~~~~~~~~~~~~ + +When you work with translations, +the workflow of your translators becomes a critical component. + +Considerations include: + +* Are your translators able to use a git workflow? For instance, are they able to translate directly via GitHub? +* Do you benefit from machine translation? +* Do you need different roles, for instance do you need translators and editors? +* What is your source language? +* When are your translated versions published? + +By using Sphinx and .po files, +you will be able to automatically synchronize between your documentation source messages on your git platform and your translation platform. + +There are many translation platforms that support this workflow. +These include: + +* `Weblate `_ +* `Transifex `_ +* `Crowdin `_ + +Because Read the Docs builds your git repository, +you can use any of the above solutions. +Any solution that synchronizes your translations with your git repository +will ensure that your translations are automatically published with Read the Docs. diff --git a/docs/user/privacy-policy.rst b/docs/user/privacy-policy.rst index 194cebbef8a..67b99518f95 100644 --- a/docs/user/privacy-policy.rst +++ b/docs/user/privacy-policy.rst @@ -1,7 +1,7 @@ .. This is linked from the footer of readthedocs.org .. and from the version (flyout) menu on docs sites -Privacy Policy +Privacy policy ============== Effective date: **September 30, 2019** diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst index e109e7cbdac..5e3e4afd240 100644 --- a/docs/user/pull-requests.rst +++ b/docs/user/pull-requests.rst @@ -2,9 +2,8 @@ Preview Documentation from Pull Requests ======================================== Your project can be configured to build and host documentation for every new -pull request. Previewing changes to your documentation during review makes it -easier to catch documentation formatting and display issues introduced in pull -requests. +pull request. Previewing changes during review makes it +easier to catch formatting and display issues before they go live. Features -------- @@ -31,81 +30,7 @@ Warning banner .. note:: Warning banners are available only for :doc:`Sphinx projects `. -Configuration -------------- - -To enable this feature for your project, -your Read the Docs account needs to be connected to an account with a supported VCS provider. -See `Limitations`_ for more information. - -If your account is already connected: - -#. Go to your project dashboard -#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings` -#. Enable the :guilabel:`Build pull requests for this project` option -#. Click on :guilabel:`Save` - -Privacy levels --------------- - -.. note:: - - Privacy levels are only supported on :doc:`/commercial/index`. - -By default, all docs built from pull requests are private. -To change their privacy level: - -#. Go to your project dashboard -#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings` -#. Select your option in :guilabel:`Privacy level of builds from pull requests` -#. Click on :guilabel:`Save` - -Privacy levels work the same way as :ref:`normal versions `. - -Limitations ------------ - -- Only available for **GitHub** and **GitLab** currently. Bitbucket is not yet supported. -- To enable this feature, your Read the Docs account needs to be connected to an - account with your VCS provider. -- Builds from pull requests have the same memory and time limitations - :doc:`as regular builds `. -- Additional formats like PDF and EPUB aren't built, to reduce build time. -- Search queries will default to the default experience for your tool. - This is a feature we plan to add, - but don't want to overwhelm our search indexes used in production. -- The built documentation is kept for 90 days after the pull request has been closed or merged. - -Troubleshooting ---------------- - -No new builds are started when I open a pull request - The most common cause is that your repository's webhook is not configured to - send Read the Docs pull request events. You'll need to re-sync your project's - webhook integration to reconfigure the Read the Docs webhook. - - To resync your project's webhook, go to your project's admin dashboard, - :guilabel:`Integrations`, and then select the webhook integration for your - provider. Follow the directions on to re-sync the webhook, or create a new - webhook integration. - - You may also notice this behavior if your Read the Docs account is not - connected to your VCS provider account, or if it needs to be reconnected. - You can (re)connect your account by going to your :guilabel:`Username dropdown`, - :guilabel:`Settings`, then to :guilabel:`Connected Services`. - - -Build status is not being reported to your VCS provider - If opening a pull request does start a new build, but the build status is not - being updated with your VCS provider, then your connected account may have out - dated or insufficient permisisons. - - Make sure that you have granted access to the Read the Docs `OAuth App`_ for - your personal or organization GitHub account. You can also try reconnecting - your account with your VCS provider. - .. seealso:: - - :ref:`integrations:Debugging webhooks` - - :ref:`github-permission-troubleshooting` -.. _OAuth App: https://github.com/settings/applications + :doc:`/guides/pull-requests` + A guide to configuring pull request builds on Read the Docs. diff --git a/docs/user/reference/404-not-found.rst b/docs/user/reference/404-not-found.rst new file mode 100644 index 00000000000..1cfba4ba00c --- /dev/null +++ b/docs/user/reference/404-not-found.rst @@ -0,0 +1,53 @@ +``404 Not Found`` pages +======================= + +If you want your project to use a custom or branded ``404 Not Found`` page, +you can put a ``404.html`` or ``404/index.html`` at the top level of your project's HTML output. + +How it works +------------ + +When our servers return a ``404 Not Found`` error, +we check if there is a ``404.html`` or ``404/index.html`` in the root of your project's output. + +The following locations are checked, in order: + +* ``/404.html`` or ``404/index.html`` in the *current* documentation version. +* ``/404.html`` or ``404/index.html`` in the *default* documentation version. + +Tool integration +---------------- + +Documentation tools will have different ways of generating a ``404.html`` or ``404/index.html`` file. +We have examples for some of the most popular tools below. + +.. tabs:: + + .. tab:: Sphinx + + We recommend the `sphinx-notfound-page`_ extension, + which Read the Docs maintains. + It automatically creates a ``404.html`` page for your documentation, + matching the theme of your project. + See its documentation_ for how to install and customize it. + + If you want to create a custom ``404.html``, + Sphinx uses `html_extra_path`_ option to add static files to the output. + You need to create a ``404.html`` file and put it under the path defined in ``html_extra_path``. + + If you are using the ``DirHTML`` builder, + no further steps are required. + Sphinx will automatically apply the ``/index.html`` folder structure to your 404 page: + ``404/index.html``. + Read the Docs also detects 404 pages named this way. + + .. tab:: MkDocs + + MkDocs automatically generates a ``404.html`` which Read the Docs will use. + However, assets will not be loaded correctly unless you define the `site_url`_ configuration value as your site's + :ref:`canonical base URL `. + +.. _sphinx-notfound-page: https://pypi.org/project/sphinx-notfound-page +.. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path +.. _documentation: https://sphinx-notfound-page.readthedocs.io/ +.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url diff --git a/docs/user/reference/analytics.rst b/docs/user/reference/analytics.rst new file mode 100644 index 00000000000..5a582bce2c4 --- /dev/null +++ b/docs/user/reference/analytics.rst @@ -0,0 +1,40 @@ +Analytics for search and traffic +================================ + +Read the Docs supports analytics for search and traffic. +When someone reads your documentation, +we collect data about the vist and the referer +with full respect of the privacy of the visitor. + + +Traffic analytics +----------------- + +Read the Docs aggregates statistics about visits to your documentation. +This is mainly information about how often pages are viewed, +and which return a `404 Not Found` error code. + +Traffic Analytics lets you see *which* documents your users are reading. +This allows you to understand how your documentation is being used, +so you can focus on expanding and updating parts people are reading most. + +If you require more detailed analytics, Read the Docs has native support for Google Analytics. +It's also possible to customize your documentation to include other analytics frameworks. + +Learn more in :doc:`/analytics`. + + +Search Analytics +---------------- + +When someone visits your documentation and uses the built-in :ref:`server-side search ` feature, +Read the Docs will collect analytics on their search term. + +Those are aggregated into a simple view of the +"Top queries in the past 30 days". +You can also download this data. + +This is helpful to optimize your documentation in alignment with your readers' interests. +You can discover new trends and expand your documentation to new needs. + +Learn more in :doc:`/guides/search-analytics`. diff --git a/docs/user/reference/cdn.rst b/docs/user/reference/cdn.rst new file mode 100644 index 00000000000..e7ed31e589b --- /dev/null +++ b/docs/user/reference/cdn.rst @@ -0,0 +1,38 @@ +Content Delivery Network (CDN) and caching +========================================== + +A CDN is used for making documentation pages *fast* for your users. +CDNs increase speed by caching documentation content in multiple data centers around the world, +and then serving docs from the data center closest to the user. + +We support CDNs on both of our sites: + +* On |org_brand|, + we are able to provide a CDN to all the projects that we host. + This service is graciously sponsored by `Cloudflare`_. +* On |com_brand|, + the CDN is included as part of our all of our plans. + We use `Cloudflare`_ for this as well. + +CDN Benefits +------------ + +Having a CDN in front of your documentation has many benefits: + +* **Improved reliability**: Since docs are served from multiple places, one can go down and the docs are still accessible. +* **Improved performance**: Data takes time to travel across space, so connecting to a server closer to the user makes documentation load faster. + +Automatic cache refresh +----------------------- + +We automatically refresh the cache on the CDN when the following actions happen: + +* Your project is saved. +* Your domain is saved. +* A new version of your documentation is built. + +By refreshing the cache according to these rules, +readers should **never see outdated content**. +This makes the end-user experience seamless, and fast. + +.. _Cloudflare: https://www.cloudflare.com/ diff --git a/docs/user/reference/environment-variables.rst b/docs/user/reference/environment-variables.rst new file mode 100644 index 00000000000..e6b4b7da445 --- /dev/null +++ b/docs/user/reference/environment-variables.rst @@ -0,0 +1,53 @@ +Environment variables +===================== + +All :doc:`build processes ` have the following environment variables automatically defined and available for each build step: + +.. envvar:: READTHEDOCS + + Whether the build is running inside Read the Docs. + + :Default: ``True`` + +.. envvar:: READTHEDOCS_PROJECT + + The :term:`slug` of the project being built. For example, ``my-example-project``. + +.. envvar:: READTHEDOCS_LANGUAGE + + The locale name, or the identifier for the locale, for the project being built. + This value comes from the project's configured language. + + :Examples: ``en``, ``it``, ``de_AT``, ``es``, ``pt_BR`` + +.. envvar:: READTHEDOCS_VERSION + + The :term:`slug` of the version being built, such as ``latest``, ``stable``, + or a branch name like ``feature-1234``. For :doc:`pull request builds `, + the value will be the pull request number. + +.. envvar:: READTHEDOCS_VERSION_NAME + + The verbose name of the version being built, such as ``latest``, ``stable``, + or a branch name like ``feature/1234``. + +.. envvar:: READTHEDOCS_VERSION_TYPE + + The type of the version being built. + + :Values: ``branch``, ``tag``, ``external`` (for :doc:`pull request builds `), or ``unknown`` + +.. envvar:: READTHEDOCS_VIRTUALENV_PATH + + Path for the :ref:`virtualenv that was created for this build `. + Only exists for builds using Virtualenv and not Conda. + + :Example: ``/home/docs/checkouts/readthedocs.org/user_builds/project/envs/version`` + +.. seealso:: + + :doc:`/environment-variables` + General information about how environment variables are used in the build process. + + :doc:`/guides/environment-variables` + Learn how to define your own custom environment variables, in addition to the pre-defined ones. diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst new file mode 100644 index 00000000000..902b2b36a22 --- /dev/null +++ b/docs/user/reference/features.rst @@ -0,0 +1,103 @@ +================= +Feature reference +================= + +.. TODO: Continue to add more features here. + +⏩️ :doc:`/custom-domains` + Documentation projects can use their own domain name. + A project may define multiple domains, + as well as define the *canonical domain* where all other domains will redirect. + + +⏩️ :doc:`/versions` + We support multiple versions and translations, + integrated nicely into the URL of your documentation. + This is served at ``/en/latest/`` by default. + If you only have 1 version and translation, + we also support :doc:`single version projects ` served at ``/``. + +⏩️ :doc:`/pull-requests` + Your project can be configured to build and host documentation for every new pull request. + Previewing changes during review makes it easier to catch formatting and display issues. + +⏩️ :doc:`/build-notifications` + Build notifications can alert you when your builds fail so you can take immediate action. + +⏩️ :doc:`/reference/analytics` + Traffic and Search analytics are built into the platform. + This allows you to easily see what the most popular pages are, + and what people are searching for. + +⏩️ :doc:`/user-defined-redirects` + Projects may define their own custom URL redirects, + with advanced functionality like folder redirects. + +⏩️ :doc:`/commercial/sharing` + It is possible to host private and password protected documentation on Read the Docs for Business. + +⏩️ :doc:`/reference/cdn` + Documentation projects are primarily static HTML pages along with media files. + This allows us to cache them with our CDN, + making them *load faster* for your users. + +⏩️ :doc:`/reference/sitemaps` + Sitemaps are generated and hosted automatically, + improving search engine optimization. + This helps your users find content more effectively on your site. + +⏩️ :doc:`/reference/404-not-found` + A 404 page is served when we can't find a page on your site. + We provide a default 404 page, + but you can also customize it. + +⏩️ :doc:`/reference/robots` + `robots.txt` files allow you to customize how your documentation is indexed in search engines. + We provide a default robots.txt file, + but you can also customize it. + +.. The TOC here will be refactored once we reorganize the files in docs/user/. +.. Probably, all feature reference should be in this directory! +.. In upcoming work, redirects will be added for old URL destinations. +.. In fact, this whole page will become a proper index page with more explanation of what sort of reference can +.. be found. + +.. toctree:: + :maxdepth: 1 + :caption: Hosting Features + + /custom-domains + /versions + /pull-requests + /build-notifications + /user-defined-redirects + /reference/analytics + /commercial/sharing + /reference/cdn + /reference/sitemaps + /reference/404-not-found + /reference/robots + +.. Move these to the above TOC once they're in the fancy list above + +.. toctree:: + :maxdepth: 1 + :caption: Business features + + /commercial/organizations + /commercial/privacy-level + /commercial/single-sign-on + +.. toctree:: + :maxdepth: 1 + :caption: Additional features + + /automation-rules + /badges + /canonical-urls + /feature-flags + /flyout-menu + /reference/environment-variables + /security-log + /server-side-search/index + /single-version diff --git a/docs/user/reference/policies.rst b/docs/user/reference/policies.rst new file mode 100644 index 00000000000..57042614ae4 --- /dev/null +++ b/docs/user/reference/policies.rst @@ -0,0 +1,48 @@ +============================ +Policies and legal documents +============================ + +Here is some of the fine print used by |org_brand| and |com_brand|: + +.. File locations are a bit odd here because of legacy. +.. We will move files to new locations and create redirects in a later refactor + +.. toctree:: + :maxdepth: 1 + :hidden: + + /abandoned-projects + /unofficial-projects + /privacy-policy + /legal/security-policy + /security + /terms-of-service + /dmca/index + /legal/dpa/index + +:doc:`/abandoned-projects` + Our policy of taking action on abandoned projects. + +:doc:`/unofficial-projects` + Our policy of taking action on unofficial and unmaintained projects. + +:doc:`/terms-of-service` + The terms of service for using |org_brand| and |com_brand|. You may instead + have a master services agreement for your subscription if you have a custom + or enterprise contract. + +:doc:`/privacy-policy` + Our policy on collecting, storing, and protecting user and visitor data. + +:doc:`/legal/security-policy` + Our policies around application and infrastructure security. + +:doc:`/security` + How we respond to security incidents and how you report a security issue. + +:doc:`/legal/dpa/index` + For GDPR and CCPA compliance, we provide a data processing addendum for + |com_brand| customers. + +:doc:`/dmca/index` + Our process for taking down content based on DMCA requests and how to submit requests. diff --git a/docs/user/reference/robots.rst b/docs/user/reference/robots.rst new file mode 100644 index 00000000000..43c667310c8 --- /dev/null +++ b/docs/user/reference/robots.rst @@ -0,0 +1,58 @@ +``robots.txt`` support +====================== + +The `robots.txt`_ files allow you to customize how your documentation is indexed in search engines. +It's useful for: + +* Hiding various pages from search engines +* Disabling certain web crawlers from accessing your documentation +* Disallowing any indexing of your documentation + +Read the Docs automatically generates one for you with a configuration that works for most projects. +By default, the automatically created ``robots.txt``: + +* Hides versions which are set to :ref:`versions:Hidden` from being indexed. +* Allows indexing of all other versions. + +.. warning:: + + ``robots.txt`` files are respected by most search engines, + but they aren't a guarantee that your pages will not be indexed. + Search engines may choose to ignore your ``robots.txt`` file, + and index your docs anyway. + + If you require *private* documentation, please see :doc:`/commercial/sharing`. + +How it works +------------ + +You can customize this file to add more rules to it. +The ``robots.txt`` file will be served from the **default version** of your project. +This is because the ``robots.txt`` file is served at the top-level of your domain, +so we must choose a version to find the file in. +The **default version** is the best place to look for it. + +Tool integration +---------------- + +Documentation tools will have different ways of generating a ``robots.txt`` file. +We have examples for some of the most popular tools below. + +.. tabs:: + + .. tab:: Sphinx + + Sphinx uses the `html_extra_path`_ configuration value to add static files to its final HTML output. + You need to create a ``robots.txt`` file and put it under the path defined in ``html_extra_path``. + + .. tab:: MkDocs + + MkDocs needs the ``robots.txt`` to be at the directory defined by the `docs_dir`_ configuration value. + +.. _robots.txt: https://developers.google.com/search/reference/robots_txt +.. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path +.. _docs_dir: https://www.mkdocs.org/user-guide/configuration/#docs_dir + +.. seealso:: + + :doc:`/guides/technical-docs-seo-guide` diff --git a/docs/user/reference/sitemaps.rst b/docs/user/reference/sitemaps.rst new file mode 100644 index 00000000000..49483613a92 --- /dev/null +++ b/docs/user/reference/sitemaps.rst @@ -0,0 +1,35 @@ +``sitemap.xml`` support +======================= + +`Sitemaps `__ allow you to inform search engines about URLs that are available for crawling. +This makes your content more :term:`discoverable `, +and improves your :doc:`Search Engine Optimization (SEO) `. + +How it works +------------ + +The ``sitemap.xml`` file is read by search engines in order to index your documentation. +It contains information such as: + +* When a URL was last updated. +* How often that URL changes. +* How important this URL is in relation to other URLs in the site. +* What translations are available for a page. + +Read the Docs automatically generates a ``sitemap.xml`` for your project, + +By default the sitemap includes: + +* Each version of your documentation and when it was last updated, sorted by version number. + +This allows search engines to prioritize results based on the version number, +sorted by `semantic versioning`_. + +Custom ``sitemap.xml`` +---------------------- + +If you need a custom sitemap, +please let us know by contacting :doc:`/support`. + +.. _semantic versioning: https://semver.org/ +.. _GitHub issue #5391: https://github.com/readthedocs/readthedocs.org/issues/5391 diff --git a/docs/user/science.rst b/docs/user/science.rst index 11ea7a2fc06..965ef4e4957 100644 --- a/docs/user/science.rst +++ b/docs/user/science.rst @@ -1,5 +1,9 @@ -Read the Docs for Science -========================= +Documentation in scientific and academic publishing +=================================================== + +On this page, we explore some of the many tools and practices that *software* documentation and *academic* writing share. +If you are working within the field of science or academia, +this page can be used as an introduction. .. 2022-08-10 .. Notes about this section: @@ -20,8 +24,7 @@ Documentation and technical writing are broad fields. Their tools and practices have grown relevant to most scientific activities. This includes building publications, books, educational resources, interactive data science, resources for data journalism and full-scale websites for research projects and courses. -Let's explore the overlap of features for software documentation and academic writing. -Here's a brief overview of some :doc:`features ` that people in science and academic writing love about Read the Docs: +Here's a brief overview of some :doc:`features ` that people in science and academic writing love about Read the Docs: .. dropdown:: 🪄 Easy to use :open: diff --git a/docs/user/security-log.rst b/docs/user/security-log.rst index 02d2f873d27..f3834ccf212 100644 --- a/docs/user/security-log.rst +++ b/docs/user/security-log.rst @@ -1,5 +1,5 @@ -Security log and auditing -========================= +Security logs +============= Security logs allow you to audit what has happened recently in your organization or account. This feature is quite important for many security compliance programs, @@ -10,49 +10,46 @@ so that you can confirm this access was from the intended person. Security logs are only visible to organization owners. You can invite other team members as owners. +.. seealso:: + + :doc:`/legal/security-policy` + General information and reference about how security is handled on Read the Docs. + User security log ----------------- -We store user security logs for the last 90 days, and track the following events: +We store a user security log for the latest 90 days of activity. +This log is useful to validate that no unauthorized events have occurred. -- Authentication on the dashboard -- Authentication on documentation pages (:doc:`/commercial/index` only) +The security log tracks the following events: -Authentication failures and successes are both tracked. - -To access your logs: +- Authentication on the dashboard. +- Authentication on documentation pages (:doc:`/commercial/index` only). +- When invitations to manage a project are sent, accepted, revoked or declined. -- Click on :guilabel:`` -- Click on :guilabel:`Settings` -- Click on :guilabel:`Security Log` +Authentication failures and successes are both tracked. -This log is useful to validate that no unauthorized logins have occured on your user account. +Logs are available in :menuselection:` --> Settings --> Security Log`. Organization security log ------------------------- -.. note:: - - This feature exists only on :doc:`/commercial/index`. +.. include:: /shared/admonition-rtd-business.rst The length of log storage varies with your plan, -check our `pricing page `__ for more details. -We track the following events: - -- Authentication on documentation pages from your organization -- User access to every documentation page from your organization (**Enterprise plans only**) +check our `pricing page `__ for more details. +Your organization security log is a great place to check periodically to ensure there hasn't been unauthorized access to your organization. -Authentication failures and successes are both tracked. +Organization logs track the following events: -To access your organization logs: +- Authentication on documentation pages from your organization. +- User accesses a documentation page from your organization (**Enterprise plans only**). +- User accesses a documentation's downloadable formats (**Enterprise plans only**). +- Invitations to organization teams are sent, revoked or accepted. -- Click on :guilabel:`` -- Click on :guilabel:`Organizations` -- Click on :guilabel:`` -- Click on :guilabel:`Settings` -- Click on :guilabel:`Security Log` +Authentication failures and successes are both tracked. -Your organization security log is a great place to check periodically to ensure there hasn't been unauthorized access to your organization. +Logs are available in :menuselection:` --> Organizations --> --> Settings --> Security Log`. If you have any additional information that you wished the security log was capturing, you can always reach out to :doc:`/support`. diff --git a/docs/user/security.rst b/docs/user/security.rst index aef5379ff4c..127dd83dd6f 100644 --- a/docs/user/security.rst +++ b/docs/user/security.rst @@ -2,8 +2,8 @@ .. https://readthedocs.org/.well-known/security.txt .. https://readthedocs.org/security/ -Security -======== +Security reports +================ Security is very important to us at Read the Docs. We follow generally accepted industry standards to protect the personal information @@ -16,20 +16,10 @@ we are committed to responsible reporting and disclosure of security issues. :backlinks: none :depth: 1 +.. seealso:: -Account security ----------------- - -* All traffic is encrypted in transit so your login is protected. -* Read the Docs stores only one-way hashes of all passwords. - Nobody at Read the Docs has access to your passwords. -* Account login is protected from brute force attacks with rate limiting. -* While most projects and docs on Read the Docs are public, - we treat your private repositories and private documentation as confidential - and Read the Docs employees may only view them - with your explicit permission in response to your support requests, - or when required for security purposes. -* You can read more about account privacy in our :doc:`privacy-policy`. + :doc:`/legal/security-policy` + Read our policy for security, which we base our security handling and reporting on. Supported versions ------------------ diff --git a/docs/user/server-side-search/api.rst b/docs/user/server-side-search/api.rst index f954c0c781b..c473da80f9c 100644 --- a/docs/user/server-side-search/api.rst +++ b/docs/user/server-side-search/api.rst @@ -7,11 +7,6 @@ If you are using :doc:`/commercial/index` you will need to replace https://readthedocs.org/ with https://readthedocs.com/ in all the URLs used in the following examples. Check :ref:`server-side-search/api:authentication and authorization` if you are using private versions. -.. contents:: Table of contents - :local: - :backlinks: none - :depth: 3 - API V3 ------ diff --git a/docs/user/server-side-search/index.rst b/docs/user/server-side-search/index.rst index cd19098e682..84aad36bf31 100644 --- a/docs/user/server-side-search/index.rst +++ b/docs/user/server-side-search/index.rst @@ -6,22 +6,17 @@ this is powered by Elasticsearch_. You can search all projects at https://readthedocs.org/search/, or search only on your project from the :guilabel:`Search` tab of your project. -.. contents:: Table of contents - :local: - :backlinks: none - :depth: 3 +.. seealso:: -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - * + :doc:`/server-side-search/syntax` + Syntax options for searching Read the Docs projects + :doc:`/server-side-search/api` + Reference to the Server Side Search API Search features --------------- -We offer a number of benefits compared to other documentation hosts: +Read the Docs has the following search features: Search across :doc:`subprojects ` Subprojects allow you to host multiple discrete projects on a single domain. @@ -65,23 +60,19 @@ API Integrate our search as you like. See :doc:`/server-side-search/api`. +Analytics + Know what your users are searching for. + See :doc:`/guides/search-analytics` + .. _"full-text search": https://docs.readthedocs.io/en/latest/search.html?q=%22full-text+search%22 .. _"project:docs project:dev search": https://docs.readthedocs.io/en/latest/search.html?q=project:docs+project:dev+search -Search analytics ----------------- - -Know what your users are looking for in your docs. -To see a list of the top queries and an overview from the last month, -go to the :guilabel:`Admin` tab of your project, -and then click on :guilabel:`Search Analytics`. - .. figure:: /_static/images/search-analytics-demo.png :width: 50% :align: center :alt: Search analytics demo - Search analytics demo + Search analytics demo. Read more in :doc:`/guides/search-analytics`. .. _Elasticsearch: https://www.elastic.co/products/elasticsearch diff --git a/docs/user/server-side-search/syntax.rst b/docs/user/server-side-search/syntax.rst index 8db8c31a9d2..579fd53e416 100644 --- a/docs/user/server-side-search/syntax.rst +++ b/docs/user/server-side-search/syntax.rst @@ -1,14 +1,9 @@ Search Query Syntax =================== -When searching on Read the Docs, you can use some parameters in your -query in order to search on given projects, versions, -or to get more accurate results. - -.. contents:: Table of contents - :local: - :backlinks: none - :depth: 3 +When searching on Read the Docs with :doc:`Server Side Search `, +you can use some parameters in your query +in order to search on given projects, versions, or to get more accurate results. Parameters ---------- diff --git a/docs/user/shared/admonition-rtd-business.rst b/docs/user/shared/admonition-rtd-business.rst index bef19220447..40936012f54 100644 --- a/docs/user/shared/admonition-rtd-business.rst +++ b/docs/user/shared/admonition-rtd-business.rst @@ -1,2 +1,2 @@ .. note:: - This feature only exists on `Read the Docs for Business `_. + This feature is only available on `Read the Docs for Business `_. diff --git a/docs/user/shared/contribute-to-troubleshooting.rst b/docs/user/shared/contribute-to-troubleshooting.rst new file mode 100644 index 00000000000..d993b2d1b81 --- /dev/null +++ b/docs/user/shared/contribute-to-troubleshooting.rst @@ -0,0 +1,5 @@ +.. tip:: + + Please help us keep this section updated and contribute your own error resolutions, performance improvements, etc. + Send in your helpful comments or ideas 💡 to support@readthedocs.org + or contribute directly by clicking :guilabel:`Edit on GitHub` in the top right corner of this page. diff --git a/docs/user/single-version.rst b/docs/user/single-version.rst new file mode 100644 index 00000000000..521511ba5b4 --- /dev/null +++ b/docs/user/single-version.rst @@ -0,0 +1,39 @@ +Single version documentation +---------------------------- + +*Single version* documentation lets you serve your documentation at the top level of your domain, +for example ``https://docs.example.com/`` or ``https://example.readthedocs.io/``. + +By default, all documentation served by Read the Docs has a standard path of ``///``. +Documentation can be served at ``/`` if you enable the *single version* option for a project. + +.. warning:: This means you can't have translations or multiple versions for your documentation. + +Having a single version of a documentation project can be considered the better choice +in cases where there should only always exist one unambiguous copy of your project. + +For example, a research project may wish to *only* expose readers to their latest list of publications and research data. +Similarly, a :abbr:`SaaS (Software as a Service)` application might only ever have one version live. + +You can see a live example of this at http://www.contribution-guide.org + +Enabling +~~~~~~~~ + +In your project's :guilabel:`Admin` page, you can toggle the :guilabel:`Single version` option on or off for your project . +Check your :term:`dashboard` for a list of your projects. + +Effects +~~~~~~~ + +Links pointing to the :term:`root URL` of the project will now point to the proper URL. +For example, if pip was set as a "Single Version" project, +then links to its documentation would point to ``https://pip.readthedocs.io/`` +rather than redirecting to ``https://pip.readthedocs.io/en/latest/``. + +.. warning:: + + Documentation at ``///`` will stop working. + Remember to set :doc:`canonical URLs ` + to tell search engines like Google what to index, + and to create :doc:`user-defined-redirects` to avoid broken incoming links. diff --git a/docs/user/single_version.rst b/docs/user/single_version.rst deleted file mode 100644 index d5000085bc2..00000000000 --- a/docs/user/single_version.rst +++ /dev/null @@ -1,31 +0,0 @@ -Single Version Documentation ----------------------------- - -Single Version Documentation lets you serve your docs at a root domain. -By default, all documentation served by Read the Docs has a root of ``///``. -But, if you enable the "Single Version" option for a project, its documentation will instead be served at ``/``. - -.. warning:: This means you can't have translations or multiple versions for your documentation. - -You can see a live example of this at http://www.contribution-guide.org - -Enabling -~~~~~~~~ - -You can toggle the "Single Version" option on or off for your project in the Project Admin page. -Check your :term:`dashboard` for a list of your projects. - -Effects -~~~~~~~ - -Links pointing to the :term:`root URL` of the project will now point to the proper URL. -For example, if pip was set as a "Single Version" project, -then links to its documentation would point to ``https://pip.readthedocs.io/`` -rather than redirecting to ``https://pip.readthedocs.io/en/latest/``. - -.. warning:: - - Documentation at ``///`` will stop working. - Remember to set :doc:`canonical URLs ` - to tell search engines like Google what to index, - and to create :doc:`user-defined-redirects` to avoid broken incoming links. diff --git a/docs/user/subprojects.rst b/docs/user/subprojects.rst index 41753175137..2d570afbb39 100644 --- a/docs/user/subprojects.rst +++ b/docs/user/subprojects.rst @@ -1,43 +1,66 @@ -Subprojects -=========== +Subprojects: host multiple projects on a single domain +====================================================== -Projects can be configured in a nested manner, by configuring a project as a -*subproject* of another project. This allows for documentation projects to share -a search index and a namespace or custom domain, but still be maintained -independently. +In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website. -For example, a parent project, ``Foo`` is set up with a subproject, ``Bar``. The -documentation for ``Foo`` will be available at: +Read the Docs can be configured to make other *projects* available on the website of the *main project* as **subprojects**. +This allows for documentation projects to share a search index and a namespace or custom domain, +but still be maintained independently. -https://foo.readthedocs.io/en/latest/ +This is useful for: -The documentation for ``Bar`` will be available under this same path: +* Organizations that need all their projects visible in one documentation portal or landing page +* Projects that document and release several packages or extensions +* Organizations or projects that want to have a common search function for several sets of documentation -https://foo.readthedocs.io/projects/bar/en/latest/ +For a main project ``example-project``, a subproject ``example-project-plugin`` can be made available as follows: -Adding a subproject -------------------- +* Main project: https://example-project.readthedocs.io/en/latest/ +* Subproject: https://example-project.readthedocs.io/projects/plugin/en/latest/ -In the admin dashboard for your project, select "Subprojects" from the menu. -From this page you can add a subproject by typing in the project slug. +.. seealso:: -Subproject aliases -~~~~~~~~~~~~~~~~~~ + :doc:`/guides/subprojects` + Learn how to create and manage subprojects + + :doc:`/guides/intersphinx` + Learn how to use references between different Sphinx projects, for instance between subprojects -You can use an alias for the subproject when it is created. This allows you to override the URL that is used to access it, giving more configurability to how you want to structure your projects. Sharing a custom domain ----------------------- -Projects and subprojects can also be used to share a custom domain with a number -of projects. To configure this, one project should be established as the parent -project. This project will be configured with a custom domain. Projects can then -be added as subprojects to this parent project. +Projects and subprojects can be used to share a custom domain. +To configure this, one project should be established as the main project and configured with a custom domain. +Other projects are then added as subprojects to the main project. + +If the example project ``example-project`` was set up with a custom domain, +``docs.example.com``, the URLs for projects ``example-project`` and ``example-project-plugin`` with alias ``plugin`` would +respectively be at: + +* ``example-project``: https://docs.example.com/en/latest/ +* ``example-project-plugin``: https://docs.example.com/projects/plugin/en/latest/ + +Using aliases +------------- + +Adding an alias for the subproject allows you to override the URL that is used to access it, +giving more control over how you want to structure your projects. +You can choose an alias for the subproject when it is created. + +You can set your subproject's project name and :term:`slug` however you want, +but we suggest prefixing it with the name of the main project. -If the example project ``Foo`` was set up with a custom domain, -``docs.example.com``, the URLs for projects ``Foo`` and ``Bar`` would -respectively be at: https://docs.example.com/en/latest/ and -https://docs.example.com/projects/bar/en/latest/ +Typically, a subproject is created with a ``-`` prefix, +for instance if the main project is called ``example-project`` and the subproject is called ``plugin``, +then the subproject's Read the Docs project :term:`slug` will be ``example-project-plugin``. +When adding the subproject, +the alias is set to ``plugin`` and the project's URL becomes +``example-project.readthedocs.io/projects/plugin``. + +When you add a subproject, +the subproject will not be directly available anymore from its own domain. +For instance, ``example-project-plugin.readthedocs.io/`` will redirect to ``example-project.readthedocs.io/projects/plugin``. Custom domain on subprojects ---------------------------- @@ -46,6 +69,22 @@ Adding a custom domain to a subproject is not allowed, since your documentation will always be served from the domain of the parent project. +Separate release cycles +----------------------- + +By using subprojects, +you can present the documentation of several projects +even though they have separate release cycles. + +Your main project may have its own versions and releases, +while all of its subprojects maintain their own individual versions and releases. +We recommend that documentation follows the release cycle of whatever it is documenting, +meaning that your subprojects should be free to follow their own release cycle. + +This is solved by having an individual :term:`flyout menu` active for the project that's viewed. +When the user navigates to a subproject, +they are presented with a flyout menu matching the subproject's versions and :doc:`/downloadable-documentation`. + Search ------ diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 5d88e5c39b1..13c825cbbed 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -665,7 +665,7 @@ Here you have some resources to continue learning about documentation and Read the Docs: - You can learn more about the functionality of the platform - by going over our :doc:`/features` page. + by going over our :doc:`features ` page. - To make the most of the documentation generators that are supported, you can read the :doc:`Sphinx tutorial ` or the `MkDocs User Guide `_. diff --git a/docs/user/unofficial-projects.rst b/docs/user/unofficial-projects.rst index 374a04da69e..851452238aa 100644 --- a/docs/user/unofficial-projects.rst +++ b/docs/user/unofficial-projects.rst @@ -1,5 +1,5 @@ -Policy for Unofficial and Unmaintained Projects -=============================================== +Unofficial and unmaintained projects policy +=========================================== This policy describes a process where we take actions against unmaintained_ and unofficial_ forks of project documentation. @@ -84,7 +84,7 @@ Projects that are determined to be unmaintained_ and unofficial_ will have a ``r # robots.txt User-agent: * - # This project is delisted according to the Policy for Unofficial and Unmaintanied Projects + # This project is delisted according to the Unofficial and Unmaintanied Project Policy # https://docs.readthedocs.io/en/stable/unofficial-projects.html Disallow: / diff --git a/docs/user/user-defined-redirects.rst b/docs/user/user-defined-redirects.rst index 6222a41a1b3..e4683196b92 100644 --- a/docs/user/user-defined-redirects.rst +++ b/docs/user/user-defined-redirects.rst @@ -1,39 +1,102 @@ -User-defined Redirects -====================== +.. old label +.. _User-defined Redirects: -You can set up redirects for a project in your project dashboard's :guilabel:`Redirects` page. +Custom and built-in redirects on Read the Docs +============================================== -.. contents:: Table of contents - :local: +Over time, a documentation project may want to rename and move contents around. +Redirects allow changes in a documentation project to happen without bad user experiences. -Quick summary -------------- +If you do not manage URL structures, +users will eventually encounter 404 File Not Found errors. +While this may be acceptable in some cases, +the bad user experience of a 404 page is usually best to avoid. -* Go to the :guilabel:`Admin` tab of your project. -* From the left navigation menu, select :guilabel:`Redirects`. -* In the form box "Redirect Type" select the type of redirect you want. - :ref:`See below ` for detail. -* Depending on the redirect type you select, enter ``From URL`` and/or ``To URL`` as needed. -* When finished, click the :guilabel:`Add` button. +`Built-in redirects`_ ⬇️ + Allows for simple and long-term sharing of external references to your documentation. -Your redirects will be effective immediately. +`User-defined redirects`_ ⬇️ + Makes it easier to move contents around (see: ) -Features --------- +.. seealso:: + + :doc:`/guides/redirects` + This guide shows you how to add redirects with practical examples. + :doc:`/automatic-redirects` + Information and tips about creating and handling external references. + :doc:`/guides/deprecating-content` + A guide to deprecating features and other topics in a documentation. + + +Special features +---------------- - By default, redirects are followed only if the requested page doesn't exist - (*404 File Not Found* error), if you need to apply a redirect for files that exist, - mark the :guilabel:`Force redirect` option. + (*404 File Not Found* error). + If you need to apply a redirect for files that exist, **This option is only available on some plan levels**. Please ask support if you need it for some reason. - :ref:`user-defined-redirects:page redirects` and :ref:`user-defined-redirects:exact redirects` can redirect to URLs outside Read the Docs, just include the protocol in ``To URL``, e.g ``https://example.com``. -Redirect types --------------- -We offer a few different type of redirects based on what you want to do. +Built-in redirects +------------------ + +This section explains the redirects that are automatically active for all projects and how they are useful. +Built-in redirects are especially useful for creating and sharing incoming links, +which is discussed indepth in :doc:`/automatic-redirects`. + +.. _page_redirects: + +Page redirects at ``/page/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can link to a specific page and have it redirect to your default version, +allowing you to create links on external sources that are always up to date. +This is done with the ``/page/`` URL prefix. + +For instance, you can reach the page you are reading now by going to https://docs.readthedocs.io/page/automatic-redirects.html. + +Another way to handle this is the ``latest`` version. +You can set your ``latest`` version to a specific version and just always link to ``latest``. +You can reach this page by going to https://docs.readthedocs.io/en/latest/automatic-redirects.html. + + +Root URL redirect at ``/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A link to the root of your documentation (`.readthedocs.io/`) will redirect to the :term:`default version`, +as set in your project settings. + +This works for both readthedocs.io (|org_brand|), readthedocs-hosted.com (|com_brand|), and :doc:`custom domains `. + +For example:: + + docs.readthedocs.io -> docs.readthedocs.io/en/stable/ + +.. warning:: + + You cannot use the root redirect to reference specific pages. + ``/`` *only* redirects to the default version, + whereas ``/some/page.html`` will *not* redirect to ``/en/latest/some/page.html``. + Instead, use :ref:`page_redirects`. + +You can choose which is the :term:`default version` for Read the Docs to display. +This usually corresponds to the most recent official release from your project. + +Shortlink with ``https://.rtfd.io`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Links to ``rtfd.io`` are treated the same way as ``readthedocs.io``. +They are intended to be easy and short for people to type. + +You can reach these docs at https://docs.rtfd.io. + + +User-defined redirects +---------------------- Prefix redirects ~~~~~~~~~~~~~~~~ @@ -163,7 +226,7 @@ Sphinx redirects ~~~~~~~~~~~~~~~~ We also support redirects for changing the type of documentation Sphinx is building. -If you switch between *HTMLDir* and *HTML*, your URL's will change. +If you switch between *HTMLDir* and *HTML*, your URLs will change. A page at ``/en/latest/install.html`` will be served at ``/en/latest/install/``, or vice versa. The built in redirects for this will handle redirecting users appropriately. diff --git a/readthedocs/api/v2/views/integrations.py b/readthedocs/api/v2/views/integrations.py index f95ce369c43..3ff940dd98a 100644 --- a/readthedocs/api/v2/views/integrations.py +++ b/readthedocs/api/v2/views/integrations.py @@ -685,9 +685,9 @@ class BitbucketWebhookView(WebhookMixin, APIView): def handle_webhook(self): """ - Handle BitBucket events for push. + Handle Bitbucket events for push. - BitBucket doesn't have a separate event for creation/deletion, instead + Bitbucket doesn't have a separate event for creation/deletion, instead it sets the new attribute (null if it is a deletion) and the old attribute (null if it is a creation). """ @@ -731,7 +731,7 @@ def handle_webhook(self): return None def is_payload_valid(self): - """BitBucket doesn't have an option for payload validation.""" + """Bitbucket doesn't have an option for payload validation.""" return True diff --git a/readthedocs/builds/models.py b/readthedocs/builds/models.py index 86af1ba9c14..230c77a11ee 100644 --- a/readthedocs/builds/models.py +++ b/readthedocs/builds/models.py @@ -897,7 +897,7 @@ def get_commit_url(self): number=self.get_version_name(), commit=self.commit ) - # TODO: Add External Version Commit URL for BitBucket. + # TODO: Add External Version Commit URL for Bitbucket. else: if 'github' in repo_url: user, repo = get_github_username_repo(repo_url) diff --git a/readthedocs/builds/tasks.py b/readthedocs/builds/tasks.py index efd01f4e08b..12bdc370266 100644 --- a/readthedocs/builds/tasks.py +++ b/readthedocs/builds/tasks.py @@ -389,7 +389,7 @@ def send_build_status(build_pk, commit, status): :param commit: commit sha of the pull/merge request :param status: build status failed, pending, or success to be sent. """ - # TODO: Send build status for BitBucket. + # TODO: Send build status for Bitbucket. build = Build.objects.filter(pk=build_pk).first() if not build: return diff --git a/readthedocs/builds/utils.py b/readthedocs/builds/utils.py index d3f33161719..f37d8f2a185 100644 --- a/readthedocs/builds/utils.py +++ b/readthedocs/builds/utils.py @@ -70,7 +70,7 @@ def get_vcs_url(*, project, version_type, version_name): repo=repo, number=version_name, ) - # TODO: Add VCS URL for BitBucket. + # TODO: Add VCS URL for Bitbucket. return '' url = '' @@ -96,7 +96,7 @@ def external_version_name(build_or_version): if project.git_provider_name == GITLAB_BRAND: return GITLAB_EXTERNAL_VERSION_NAME - # TODO: Add External Version Name for BitBucket. + # TODO: Add External Version Name for Bitbucket. return GENERIC_EXTERNAL_VERSION_NAME diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index da3be074982..221d6952f31 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -243,7 +243,7 @@ def get_config_params(self): 'github_version_is_editable': github_version_is_editable, 'display_github': display_github, - # BitBucket + # Bitbucket 'bitbucket_user': bitbucket_user, 'bitbucket_repo': bitbucket_repo, 'bitbucket_version': remote_version, diff --git a/readthedocs/oauth/services/bitbucket.py b/readthedocs/oauth/services/bitbucket.py index 6c2a6755830..9de55f56e87 100644 --- a/readthedocs/oauth/services/bitbucket.py +++ b/readthedocs/oauth/services/bitbucket.py @@ -239,7 +239,7 @@ def get_webhook_data(self, project, integration): def get_provider_data(self, project, integration): """ - Gets provider data from BitBucket Webhooks API. + Gets provider data from Bitbucket Webhooks API. :param project: project :type project: Project diff --git a/readthedocs/projects/models.py b/readthedocs/projects/models.py index b935295dbfd..b7d80730c07 100644 --- a/readthedocs/projects/models.py +++ b/readthedocs/projects/models.py @@ -951,7 +951,7 @@ def git_service_class(self): @property def git_provider_name(self): - """Get the provider name for project. e.g: GitHub, GitLab, BitBucket.""" + """Get the provider name for project. e.g: GitHub, GitLab, Bitbucket.""" service = self.git_service_class() if service: provider = allauth_registry.by_id(service.adapter.provider_id) diff --git a/readthedocs/templates/homepage.html b/readthedocs/templates/homepage.html index d25b12fa418..96757dd222a 100644 --- a/readthedocs/templates/homepage.html +++ b/readthedocs/templates/homepage.html @@ -70,7 +70,7 @@

{% trans "Always up to date" %}

{% blocktrans trimmed %} Whenever you push code to your favorite version control service, - whether that is GitHub, BitBucket, or GitLab, we will + whether that is GitHub, Bitbucket, or GitLab, we will automatically build your docs so your code and documentation are never out of sync. {% endblocktrans %} diff --git a/requirements/docs.txt b/requirements/docs.txt index 7e2d188be93..fcbd4a36da2 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -115,6 +115,8 @@ sphinxcontrib-jquery==2.0.0 # sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx +sphinxcontrib-mermaid==0.7.1 + # via -r requirements/docs.in sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5