readthedocs · astrojuanlu · Sep 28, 2021 · Sep 27, 2021 · Sep 27, 2021 · Sep 27, 2021
diff --git a/docs/advertising/advertising-details.rst b/docs/advertising/advertising-details.rst
@@ -119,13 +119,13 @@ our own goals.
 
 We have taken steps to address some of the privacy concerns surrounding GA.
 These steps apply both to analytics collected by Read the Docs and when
-:doc:`authors enable analytics on their docs </guides/google-analytics>`.
+:ref:`authors enable analytics on their docs <analytics:Enabling Google Analytics on your Project>`.
 
 * Users can opt-out of analytics by using the Do Not Track feature of their browser.
 * Read the Docs instructs Google to anonymize IP addresses sent to them.
 * The cookies set by GA expire in 30 days rather than the default 2 years.
 * Project maintainers can completely disable analytics on their own projects.
-  Follow the steps in :ref:`guides/google-analytics:Disabling Google Analytics on your project`.
+  Follow the steps in :ref:`analytics:Disabling Google Analytics on your project`.
 
 
 Why we use analytics

diff --git a/docs/analytics.rst b/docs/analytics.rst
@@ -1,7 +1,7 @@
-Analytics
----------
+Traffic Analytics
-Traffic Analytics
+Traffic Analytics - See top performing doc pages
-Traffic Analytics
+Traffic Analytics - See top performing doc pages
+=================
 
-Analytics lets you see *which* documents your users are reading.
+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.
 
@@ -18,7 +18,36 @@ and then click on :guilabel:`Traffic Analytics`.
 
 You can also access to analytics data from :ref:`search results <server-side-search:analytics>`.
 
+Enabling Google Analytics on your Project
+-----------------------------------------
+
+Read the Docs has native support for Google Analytics.
+You can enable it by:
+
+* Going to :guilabel:`Admin` > :guilabel:`Advanced Settings` in your project.
+* Fill in the **Analytics code** heading with your Google Tracking ID (example `UA-123456674-1`)
+
+Once your documentation rebuilds it will include your Analytics tracking code and start sending data.
+Google Analytics usually takes 60 minutes,
+and sometimes can take up to a day before it starts reporting data.
+
 .. note::
 
-   If you require more information about page views,
-   you can use a solution like :doc:`Google Analytics </guides/google-analytics>`.
+   Read the Docs takes some extra precautions with analytics to protect user privacy.
+   As a result, users with Do Not Track enabled will not be counted
+   for the purpose of analytics.
+
+   For more details, see the
+   :ref:`Do Not Track section <privacy-policy:Do Not Track>`
+   of our privacy policy.
+
+Disabling Google Analytics on your project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Google Analytics can be completely disabled on your own projects.
+To disable Google Analytics:
+
+* Going to :guilabel:`Admin` > :guilabel:`Advanced Settings` in your project.
+* Check the box **Disable Analytics**.
+
+Your documentation will need to be rebuilt for this change to take effect.
diff --git a/docs/guides/build-notifications.rst → docs/build-notifications.rst b/docs/guides/build-notifications.rst → docs/build-notifications.rst
diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst
@@ -133,41 +133,52 @@ You will need to update your CAA records to allow us to issue the certificate.
    to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs,
    else it will always redirect to GitBook.
 
-Proxy SSL
----------
-
-.. warning::
-
-   This option is deprecated,
-   we already issue SSL certificates for all domains.
-
-If you would prefer to do your own SSL termination
-on a server you own and control,
-you can do that although the setup is a bit more complex.
-
-Broadly, the steps are:
-
-* Have a server listening on 443 that you control
-* Procure an SSL certificate for your domain and provision it
-  and the private key on your server.
-* Add a domain that you wish to point at Read the Docs
-* Enable proxying to us, with a custom ``X-RTD-SLUG`` header
-
-An example nginx configuration for pip would look like:
-
-.. code-block:: nginx
-   :emphasize-lines: 9
-
-    server {
-        server_name pip.pypa.io;
-        location / {
-            proxy_pass https://pip.readthedocs.io:443;
-            proxy_set_header Host $http_host;
-            proxy_set_header X-Forwarded-Proto https;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Scheme $scheme;
-            proxy_set_header X-RTD-SLUG pip;
-            proxy_connect_timeout 10s;
-            proxy_read_timeout 20s;
-        }
-    }
+Canonical URLs
+--------------
+
+Canonical URLs allow people to have consistent page URLs for domains.
+This is mainly useful for search engines,
+so that they can send people to the correct page.
+
+Read the Docs uses these in two ways:
+
+* We point all versions of your docs at the "latest" version as canonical
+* We point at the user specified canonical URL, generally a custom domain for your docs.
+
+Example
++++++++
+
+Fabric hosts their docs on Read the Docs.
+They mostly use their own domain for them ``http://docs.fabfile.org``.
+This means that Google will index both ``http://fabric-docs.readthedocs.io`` and
+``http://docs.fabfile.org`` for their documentation.
+
+Fabric will want to set ``http://docs.fabfile.org`` as their canonical URL.
+This means that when Google indexes ``http://fabric-docs.readthedocs.io``,
+it will know that it should really point at ``http://docs.fabfile.org``.
+
+Enabling
+++++++++
+
+You can set the canonical URL for your project in the Project Admin page.
+Check your :guilabel:`Admin` > :guilabel:`Domains` page for the domains that we know about.
+
+Implementation
+++++++++++++++
+
+If you are using :doc:`Sphinx </intro/getting-started-with-sphinx>`,
+Read the Docs will set the value of the html_baseurl_ setting (if isn't already set) to your canonical domain.
+
+.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl
+
+If you are using :doc:`MkDocs </intro/getting-started-with-mkdocs>`,
+you can use the site_url_ setting.
+
+.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url
+
+If you look at the source code for documentation built after you set your canonical URL,
+you should see a bit of HTML like this:
+
+.. code-block:: html
+
+    <link rel="canonical" href="http://docs.fabfile.org/en/2.4/" />
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -50,7 +50,7 @@ see :ref:`faq:My documentation requires additional dependencies`.
 Read the Docs offers some settings which can be used for a variety of purposes.
 To enable these settings,
 please send an email to support@readthedocs.org and we will change the settings for the project.
-Read more about these settings :doc:`here <guides/feature-flags>`.
+Read more about these settings :doc:`here <feature-flags>`.
 
 
 I get import errors on libraries that depend on C modules

diff --git a/docs/guides/feature-flags.rst → docs/feature-flags.rst b/docs/guides/feature-flags.rst → docs/feature-flags.rst
diff --git a/docs/features.rst b/docs/features.rst
@@ -71,7 +71,7 @@ We offer a number of search features:
 * Search across :doc:`subprojects </subprojects>`
 * Search results land on the exact content you were looking for
 * Search across projects you have access to (available on |com_brand|)
-* A full range of :doc:`search operators </guides/searching-with-readthedocs>` including exact matching and excluding phrases.
+* A full range of :doc:`search operators </guides/advanced-search>` including exact matching and excluding phrases.
 
 Learn more about :doc:`/server-side-search`.
 

diff --git a/docs/guides/administrators.rst b/docs/guides/administrators.rst
@@ -0,0 +1,22 @@
+Guides for project administrators
+---------------------------------
+
+These guides cover common use cases
+relevant for managing documentation projects,
+using the Read the Docs web interface,
+and making changes to the configuration files.
+
+For an introduction to Read the Docs,
+have a look at our :doc:`/tutorial/index`.
+
+.. toctree::
+   :maxdepth: 1
+
+   technical-docs-seo-guide
+   manage-translations-sphinx
+   advanced-search
+   hiding-a-version
+   deprecating-content
+   pdf-non-ascii-languages
+   importing-private-repositories
+   wipe-environment
diff --git a/docs/guides/searching-with-readthedocs.rst → docs/guides/advanced-search.rst b/docs/guides/searching-with-readthedocs.rst → docs/guides/advanced-search.rst
@@ -1,5 +1,5 @@
-Searching with Read the Docs
-============================
+Using advanced search features
+==============================
 
 Read the Docs uses :doc:`/server-side-search` to power our search.
 This guide explains how to add a "search as you type" feature to your documentation,

diff --git a/docs/guides/authors.rst b/docs/guides/authors.rst
@@ -0,0 +1,18 @@
+Guides for documentation authors
+--------------------------------
+
+These guides offer some tips and tricks to author documentation
+with the tools supported on Read the Docs.
+Only reStructuredText or Markdown knowledge
+and minimal configuration tweaking are needed.
+
+For an introduction to Sphinx and Mkdocs,
+have a look at our :doc:`/intro/getting-started-with-sphinx`
+and :doc:`/intro/getting-started-with-mkdocs`.
+
+.. toctree::
+   :maxdepth: 1
+
+   cross-referencing-with-sphinx
+   intersphinx
+   jupyter
diff --git a/docs/guides/canonical.rst b/docs/guides/canonical.rst
diff --git a/docs/guides/commercial.rst b/docs/guides/commercial.rst
diff --git a/docs/guides/conda.rst b/docs/guides/conda.rst
@@ -62,7 +62,7 @@ so they can have any value, or not be present at all.
 .. warning:: Pinning Sphinx and other Read the Docs core dependencies
    is not yet supported by default when using conda (see `this GitHub issue for discussion`_).
    If your project needs it, request that we enable the ``CONDA_APPEND_CORE_REQUIREMENTS``
-   :ref:`feature flag <guides/feature-flags:Feature Flags>`.
+   :ref:`feature flag <feature-flags:Feature Flags>`.
 
 .. _this GitHub issue for discussion: https://github.com/readthedocs/readthedocs.org/issues/3829
 .. _exporting a conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#sharing-an-environment
@@ -178,7 +178,7 @@ minimize the running time or the memory usage:
   and opting out of the defaults adding ``nodefaults``.
 - Constrain the package versions as much as possible to reduce the solution space.
 - Use mamba_, an alternative package manager fully compatible with conda packages,
-  by requesting the ``CONDA_USES_MAMBA`` :ref:`feature flag <guides/feature-flags:Feature Flags>`.
+  by requesting the ``CONDA_USES_MAMBA`` :ref:`feature flag <feature-flags:Feature Flags>`.
 - And, if all else fails,
   :ref:`request more resources <guides/build-using-too-many-resources:Requests more resources>`.
 

diff --git a/docs/guides/deprecating-content.rst b/docs/guides/deprecating-content.rst
@@ -1,5 +1,5 @@
-Deprecating Content on Read the Docs
-====================================
+Deprecating Content
+===================
 
 When you deprecate a feature from your project,
 you may want to deprecate its docs as well,
@@ -40,8 +40,8 @@ and mark the :guilabel:`Hidden` option. Check :ref:`versions:Version States` for
 
    .. _semver: https://semver.org/
 
-Deprecating content
--------------------
+Deprecating pages
+-----------------
 
 You may not always want to deprecate a version, but deprecate some pages.
 For example, if you have documentation about two APIs and you want to deprecate v1:

diff --git a/docs/guides/developers.rst b/docs/guides/developers.rst
@@ -0,0 +1,19 @@
+Guides for developers and designers
+-----------------------------------
+
+These guides are helpful for developers and designers
+seeking to extend the authoring tools
+or customize the documentation appearance.
+
+.. toctree::
+   :maxdepth: 1
+
+   private-python-packages
+   private-submodules
+   adding-custom-css
+   reproducible-builds
+   embedding-content
+   conda
+   remove-edit-buttons
+   build-using-too-many-resources
+   vcs
diff --git a/docs/guides/google-analytics.rst b/docs/guides/google-analytics.rst
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -11,6 +11,6 @@ and how to write successful documentation.
 .. toctree::
    :maxdepth: 2
 
-   tools
-   platform
-   commercial
+   authors
+   administrators
+   developers