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/downloadable-documentation.rst b/docs/user/downloadable-documentation.rst index 761a29fff74..0835215359f 100644 --- 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 index f11b2182387..bee3292d65d 100644 --- 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) jupyter Migrate from rST to MyST + enable-offline-formats diff --git a/docs/user/guides/enable-offline-formats.rst b/docs/user/guides/enable-offline-formats.rst new file mode 100644 index 00000000000..ae4502a6c8c --- /dev/null +++ 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 index 8e80ade445a..747067e820f 100644 --- 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