diff --git a/docs/user/guides/hosting-integrations.rst b/docs/user/guides/hosting-integrations.rst new file mode 100644 index 00000000000..105b106acfe --- /dev/null +++ b/docs/user/guides/hosting-integrations.rst @@ -0,0 +1,249 @@ +Hosting Integrations +==================== + + +.. This document is not ready to be presented to our users and tell them to integrate with us. + It has been more useful as an internal exercise to understand how our integrations work, + and be able to standardize and migrate them out from the build process to a JavaScript library. + + Note there are already some integrations that happens statically at build time by using a Sphinx extension, + or application code, and there are others that happen dynamically via our current JavaScript library. + +This page explains the manual steps required to integrate all the hosting features when overriding the build process by using ``build.commands`` configuration +(see :doc:`/build-customization`). +As Read the Docs does not have control over the build process, +it cannot install and inject the required extensions to automatically integrate them. +You are encourage to read this document and understand the "behind the scenes" to integrate these features by yourself. +This can be done by running user-defined commands in the build process or by creating a doctool extensions +that execute these actions as part of the build itself. + +These are all the hosting features that Read the Docs provides by default: + +`Flyout menu`_ + Menu displaying on all documentation pages containing the list of active versions, + downloadable formats and other useful links. + Read more at :doc:`/flyout-menu`. + +`Search index`_ + Smart search index powered by Elasticsearch able to differentiate between regular text, + function names in code, and search in all subprojects, among others. + Read more at :doc:`/server-side-search`. + +`Search as you type`_ + Level up your search by providing immediate feedback while the user is typing. + Read more at :doc:`/advanced-search.html#enable-search-as-you-type-in-your-documentation`. + +`Version warning`_ + Banner displayed on old versions when there is a newer version available, + communicating readers they may be careful since they are reading an older version of the documentation. + Read more at :doc:`/versions#version-warning`. + +`External (pull request) version warning`_ + Benner displayed on versions of the documentation built from an external version (pull request), + warning readers this is not the final version of this documentation. + Read more at :doc:`/pull-requests`. + +.. TODO: write a new page explaining this and link it from here. +`Telemetry`_ + Build data stored by Read the Docs (e.g. Python packages installed) for better understanding about + how users use the platform and keep it stable. + Read more in our blog post + `Knowing more about how people use our service `_ + +`Advertisement`_ + Ad shown on documentation pages that helps Read the Docs to be sustainable. + Read more at :doc:`/advertising`. + +`Google Analytics`_ + Google Analytics integration to track pageviews on your documentation. + Read more at :doc:`/analytics:Enabling Google Analytics on your Project`. + + +.. TODO: explain "Visual diff" when we have it available for our users. + + +Flyout menu +----------- + +Displying the flyout menu requires adding some Javascript and CSS files in each of the documentation pages. +These files have to be added inside the ```` tag: + +.. code-block:: html + :linenos: + :emphasize-lines: 22,23 + + + + + + + + + +Note that you have to change the highlighted lines with your project and version slugs. + +Besides including these files, +a ``div`` tag is required to define *where* the flyout menu will be displayed. +This tag has to be added inside the ```` tag: + +.. code-block:: html + :linenos: + + +
+ + +Telemetry +--------- + +Read the Docs expects the file ``_build/json/telemetry.json`` once the build has finished. +This file contains a list of doctool extensions/plugins installed to perform the build +and also the HTML theme used. + +The data is organized in a JSON file as follows: + +.. code-block:: json + :linenos: + + { + "extensions": [ + "module.extension" + ], + "html_theme": "name" + } + + +Advertisement +------------- + +Advertisement makes Read the Docs sustainable and free for Open Source projects. +Similarly to the flyout_, it requires including the same Javascript and stylesheet files +(you can copy the code from the previous section), +plus a ``div`` specifying *where* the Ad should be shown: + +.. NOTE: should we tell people to integrate it using the ``readthedocs-doc-embed.js`` file, + or should they use the EthicalAds client directly? + +.. code-block:: html + :linenos: + + +
+
+
+ + +.. note:: + + Make sure to not include the Javascript and stylesheet twice when integrating the Flyout_ and Advertisement_. + That chunk of HTML code is exactly the same and shared between both. + They should be included only once in the page. + + +External (pull request) version warning +--------------------------------------- + +On each build built from a pull requests, +a warning banner is added to communicate readers this particular version of the documentation is not in production +and it's still under review. + +Read the Docs adds the following HTML to create the warning admonition: + +.. NOTE: we should standardize this by providing the CSS as well and making it sticky (maybe at the top). + Now, it's injected at a particular place in the HTML structure --which won't be general for all the doctools. + Besides, we are inject it using a Sphinx extension that may differ what's the outputed HTML (based on docutils version). + +.. code-block:: html + :linenos: + :emphasize-lines: 5,7 + +
+

Warning

+

+ This page + was created + from a pull request + (#PRNUMBER). +

+
+ +Note in the highlighted lines there are some placeholders for: + +* Read the Docs' project slug +* Read the Docs' build id +* GitHub username +* GitHub pull request number + +These placeholders should be replaced by the real values. + + +Version warning +--------------- + +Read the Docs adds a warning banner at the top of each documentation page +when the reader visits an old page when there is a newer version of the same page available. + +.. NOTE: this has the same non-standardized issue as the "External version warning" + + +.. code-block:: html + :linenos: + :emphasize-lines: 5,7 + +
+

Warning

+

+ This page documents version + . + The latest version is + . +

+
+ +Note in the highlighted lines there are some placeholders for: + +* Read the Docs' project slug +* Read the Docs' language +* Read the Docs' current version (old) +* Read the Docs' new version + + +Google Analytics +---------------- + +Read the Docs uses Google Analytics behind the scenes to track pageviews. +Besides, if the user defines a Google Analytics code, pageviews will also be sent to it. + +.. code-block:: html + :linenos: + :emphasize-lines: 3 + + + +.. The GA4 JavaScript required for this is inject dynamically at: + https://github.com/readthedocs/readthedocs.org/blob/cfecfb9b7da783aa856ffad82ea5cec474d2f31c/media/javascript/readthedocs-analytics.js#L9-L44 + + In that file, "global_analytics_code" and "user_analytics_code" is injected + via the readthedocs-sphinx-ext.