Refactor downloadable docs (#9768)

ericholscher · benjaoming · web-flow · commit 6435054bdf65 · 2022-12-06T14:38:26.000-08:00
* Refactor offline formats docs Refs #9746 Closes #9577 * Apply suggestions from code review Co-authored-by: Benjamin Balder Bach <benjamin@readthedocs.org> * Update docs/user/downloadable-documentation.rst Co-authored-by: Benjamin Balder Bach <benjamin@readthedocs.org> * Lots of updates from feedback * Fix CI * Move to Explanation * Update docs/user/downloadable-documentation.rst Co-authored-by: Benjamin Balder Bach <benjamin@readthedocs.org> * Fix lint Co-authored-by: Benjamin Balder Bach <benjamin@readthedocs.org>
diff --git a/docs/user/_static/images/guides/offline-formats.jpg b/docs/user/_static/images/guides/offline-formats.jpg
diff --git a/docs/user/downloadable-documentation.rst b/docs/user/downloadable-documentation.rst
@@ -1,50 +1,85 @@
-Downloadable Documentation
-==========================
+Understanding Offline Formats
+=============================
 
-Read the Docs supports building multiple formats for Sphinx-based projects:
+This page will provide an overview of a core Read the Docs feature: building docs in multiple formats.
+
+Read the Docs supports the following formats by default:
 
 * PDF
 * ePub
 * Zipped HTML
 
-This means that every commit that you push will automatically update your PDFs as well as your HTML.
+This means that every commit that you push will automatically update your offline formats as well as your documentation website.
+
+Use cases
+---------
+
+This functionality is great for anyone who needs documentation when they aren't connected to the internet.
+Users who are about to get on a plane can grab a single file and have the entire documentation during their trip.
+Many academic and scientific projects benefit from these additional formats.
+
+PDF versions are also helpful to automatically **create printable versions of your documentation**.
+The source of your documentation will be structured to support both online and offline formats.
+This means that a documentation project displayed as a website can be downloaded as a PDF,
+ready to be printed as a report or a book.
+
+Offline formats also support having the entire documentation in a single file.
+Your entire documentation can now be delivered as an email attachment,
+uploaded to an eReader,
+or accessed and searched locally without online latency.
+This makes your documentation project **easy to redistribute or archive**.
 
-This is enabled by the :ref:`config-file/v2:formats` key in our config file.
-A simple example is here:
+Accessing offline formats
+-------------------------
 
-.. code-block:: yaml
+You can download offline formats in the :guilabel:`Project dashboard` > :guilabel:`Downloads`:
 
-   # Build PDF & ePub
-   formats:
-     - epub
-     - pdf
+.. image::  /_static/images/guides/offline-formats.jpg
+    :width: 75%
+
+When you are browsing a documentation project,
+they can also be accessed directly from the :doc:`/flyout-menu`.
+
+Examples
+--------
 
 If you want to see an example,
 you can download the Read the Docs documentation in the following formats:
 
-    * `PDF`_ 
-    * `ePub`_ 
-    * `Zipped HTML`_ 
-    
+    * `PDF`_
+    * `ePub`_
+    * `Zipped HTML`_
+
 .. _PDF: https://docs.readthedocs.io/_/downloads/en/latest/pdf/
 .. _ePub: https://docs.readthedocs.io/_/downloads/en/latest/epub/
 .. _Zipped HTML: https://docs.readthedocs.io/_/downloads/en/latest/htmlzip/
 
-Use cases
----------
+Continue learning
+-----------------
 
-This functionality is great for anyone who needs documentation when they aren't connected to the internet.
-Users who are about to get on a plane can grab a PDF and have the entire doc set ready for their trip.
+Downloadable documentation formats are built by your documentation framework.
+They are then published by Read the Docs and included in your :term:`Flyout menu`.
+Therefore, it's your framework that decides exactly how each output is built and which formats are supported:
+
+Sphinx
+   All output formats are built mostly lossless from the documentation source,
+   meaning that your documentation source (reStructuredText or Markdown/MyST) is built from scratch for each output format.
+
+MkDocs and Docsify + more
+   The common case for most documentation frameworks is that several alternative extensions exist supporting various output formats.
+   Most of the extensions export the HTML outputs as another format (for instance PDF) through a conversion process.
 
-The other value is having the entire docset in a single file.
-You can send a user an email with a single PDF or ePub and they'll have all the docs in one place.
+Because Sphinx supports the generation of downloadable formats through an official process,
+we are also able to support it officially.
+Other alternatives can also work,
+provided that you identify which extension you want to use and configure the environment for it to run.
+**Other formats aren't natively supported by Read the Docs,
+but support is coming soon.**
 
-Deleting downloadable content
------------------------------
+.. seealso::
 
-The entries in the Downloads section of your project dashboard reflect the
-formats specified in your config file for each active version.
+   Other pages in our documentation are relevant to this feature,
+   and might be a useful next step.
 
-This means that if you wish to remove downloadable content for a given version,
-you can do so by removing the matching :ref:`config-file/v2:formats` key from
-your config file.
+   * :doc:`/guides/enable-offline-formats` - Guide to enabling and disabling this feature.
+   * :ref:`config-file/v2:formats` - Configuration file options for offline formats.
diff --git a/docs/user/guides/authors.rst b/docs/user/guides/authors.rst
@@ -17,3 +17,4 @@ and :doc:`/intro/getting-started-with-mkdocs`.
    Link to external projects (Intersphinx) <intersphinx>
    jupyter
    Migrate from rST to MyST <migrate-rest-myst>
+   enable-offline-formats
diff --git a/docs/user/guides/enable-offline-formats.rst b/docs/user/guides/enable-offline-formats.rst
@@ -0,0 +1,54 @@
+How to enable offline formats
+=============================
+
+This guide provides **step-by-step instructions to enabling offline formats** of your documentation.
+
+They are automatically built by Read the Docs during our default build process,
+as long as you have the configuration enabled to turn this on.
+
+Enabling offline formats
+------------------------
+
+Offline formats are enabled by the :ref:`config-file/v2:formats` key in our config file.
+A simple example is here:
+
+.. code-block:: yaml
+
+   # Build PDF & ePub
+   formats:
+     - epub
+     - pdf
+
+Verifying offline formats
+-------------------------
+
+You can verify that offline formats are building in your :guilabel:`Project dashboard` > :guilabel:`Downloads`:
+
+.. image::  /_static/images/guides/offline-formats.jpg
+    :width: 75%
+
+Deleting offline formats
+------------------------
+
+The entries in the Downloads section of your project dashboard reflect the
+formats specified in your config file for each active version.
+
+This means that if you wish to remove downloadable content for a given version,
+you can do so by removing the matching :ref:`config-file/v2:formats` key from
+your config file.
+
+
+Continue learning
+-----------------
+
+.. seealso::
+
+   Other pages in our documentation are relevant to this feature,
+   and might be a useful next step.
+
+
+   * :doc:`/downloadable-documentation` - Overview of this feature.
+   * :ref:`config-file/v2:formats` - Configuration file options for offline formats.
+
+   ..
+      TODO: Link to our build customization page on this once we write it.
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -77,6 +77,7 @@ to help you create fantastic documentation for your project.
    :caption: Explanation
 
    /build-notifications
+   /downloadable-documentation
 
 
 .. toctree::
@@ -145,7 +146,6 @@ and some of the core features of Read the Docs.
    /integrations
    /custom-domains
    /versions
-   /downloadable-documentation
    /hosting
    /server-side-search/index
    /analytics
