Merge pull request #5893 from readthedocs/davidfischer/guides-restructure

Rework on documentation guides

Author: davidfischer

docs/guides/adding-custom-css.rst

@@ -1,25 +1,79 @@
-Adding Custom CSS or JavaScript to a Sphinx Project
-===================================================
+Adding Custom CSS or JavaScript to Sphinx Documentation
+=======================================================
 
-The easiest way to add custom stylesheets or scripts, and ensure that the files
-are added in a way that allows for overriding of existing styles or scripts, is
-to add these files using a ``conf.py`` Sphinx extension. Inside your
-``conf.py``, if a function ``setup(app)`` exists, Sphinx will call this function
-as a normal extension during application setup.
+.. meta::
+   :description lang=en:
+       How to add additional CSS stylesheets or JavaScript files
+       to your Sphinx documentation
+       to override your Sphinx theme or add interactivity with JavaScript.
 
-For example, if a custom stylesheet exists at ``_static/css/custom.css``, a
-``conf.py`` extension can be written to add this file to the list of
-stylesheets::
+Adding additional CSS or JavaScript files to your Sphinx documentation
+can let you customize the look and feel of your docs
+or add additional functionality.
+For example, with a small snippet of CSS,
+your documentation could use a custom font or have a different background color.
 
-    def setup(app):
-        app.add_stylesheet('css/custom.css')
+If your custom stylesheet is ``_static/css/custom.css``,
+you can add that CSS file to the documentation using the
+Sphinx option `html_css_files`_::
 
-Using an extension to add the stylesheet allows for the file to be added to the
-list of stylesheets later in the Sphinx setup process, making overriding parts
-of the Read the Docs theme possible.
+    ## conf.py
 
-The same method can be used to add additional scripts that might override
-previously initialized scripts::
+    # These folders are copied to the documentation's HTML output
+    html_static_path = ['_static']
 
-    def setup(app):
-        app.add_javascript('js/custom.js')
+    # These paths are either relative to html_static_path
+    # or fully qualified paths (eg. https://...)
+    html_css_files = [
+        'css/custom.css',
+    ]
+
+
+A similar approach can be used to add JavaScript files::
+
+    html_js_files = [
+        'js/custom.js',
+    ]
+
+
+
+.. _html_css_files: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_css_files
+
+.. note::
+
+    The Sphinx HTML options ``html_css_files`` and ``html_js_files``
+    where added in Sphinx 1.8.
+    Unless you have a good reason to use an older version,
+    you are strongly encouraged to upgrade.
+    Sphinx is almost entirely backwards compatible.
+
+
+Overriding or replacing a theme's stylesheet
+--------------------------------------------
+
+The above approach is preferred for adding additional stylesheets or JavaScript,
+but it is also possible to completely replace a Sphinx theme's stylesheet
+with your own stylesheet.
+
+If your replacement stylesheet exists at ``_static/css/yourtheme.css``,
+you can replace your theme's CSS file by setting ``html_style`` in your ``conf.py``::
+
+    ## conf.py
+
+    html_style = 'css/yourtheme.css'
+
+If you only need to override a few styles on the theme,
+you can include the theme's normal CSS using the CSS
+`@import rule <https://developer.mozilla.org/en-US/docs/Web/CSS/@import>`_ .
+
+.. code-block:: css
+
+    /** css/yourtheme.css **/
+
+    /* This line is theme specific - it includes the base theme CSS */
+    @import '../alabaster.css';  /* for Alabaster */
+    /*@import 'theme.css';       /* for the Read the Docs theme */
+
+    body {
+        /* ... */
+    }

docs/guides/custom-404-page.rst

@@ -1,5 +1,5 @@
-Use custom ``404 Not Found`` page on my project
-===============================================
+Use a Custom ``404 Not Found`` Page on my Project
+=================================================
 
 If you want your project to use a custom page for not found pages instead of the "Maze Found" default one,
 you can put a ``404.html`` at the top level of your project's HTML output.

docs/guides/index.rst

@@ -1,11 +1,44 @@
 Guides
 ======
 
-These guides will help walk you through the usage of Read the Docs.
+These guides will help walk you through specific use cases
+related to Read the Docs itself, documentation tools like Sphinx and MkDocs
+and how to write successful documentation.
 
 
+Sphinx & MkDocs how-to guides
+-----------------------------
+
+These guides will help you get the most out of your documentation authoring tool
+whether that is Sphinx or MkDocs.
+
+.. toctree::
+    :maxdepth: 1
+
+    adding-custom-css
+    custom-404-page
+    manage-translations
+    mkdocs-old-versions
+    pdf-non-ascii-languages
+    remove-edit-buttons
+    vcs
+
+
+Read the Docs how-to guides
+---------------------------
+
+These guides will help you customize or tune aspects of the Read the Docs build environment.
+
 .. toctree::
-   :maxdepth: 1
-   :glob:
+    :maxdepth: 1
 
-   *
+    build-notifications
+    build-using-too-many-resources
+    canonical
+    conda
+    environment-variables
+    feature-flags
+    google-analytics
+    sitemaps
+    specifying-dependencies
+    wipe-environment

docs/guides/mkdocs-old-versions.rst

@@ -1,7 +1,8 @@
-Keep Building Docs With Old Version Of MkDocs
-=============================================
+Building With Pre-1.0 Versions Of MkDocs
+========================================
 
-Recent changes to ``mkdocs`` forced us to `upgrade the default version installed`_ by Read the Docs and this may be a breaking change for your documentation.
+Recent changes to ``mkdocs`` forced us to `upgrade the default version installed`_ by Read the Docs
+and this may be a breaking change for your documentation.
 
 .. _upgrade the default version installed: https://github.com/readthedocs/readthedocs.org/pull/4041
 
@@ -15,8 +16,8 @@ In case your builds are failing because of a ``mkdocs`` issue,
 you may want to follow one of the following solutions depending on the case.
 
 
-Pin mkdocs to the previous version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Pin MkDocs to an older version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Before Read the Docs upgraded its default version installed, ``mkdocs==0.15.0`` was used.
 To make your project continue using this version you will need to create a ``requirements.txt`` file with this content::
@@ -27,21 +28,15 @@ To make your project continue using this version you will need to create a ``req
      mkdocs-bootswatch==0.1.0
      markdown>=2.3.1,<2.5
 
-.. note::
-
-   Most of the breaking changes where introduced in ``mkdocs==0.17``,
-   so you may want to test only pinning ``mkdocs`` to ``mkdocs<0.17``
-   and check if your docs keep building successfully.
-
 
 More detailed information about how to specify dependencies can be found :ref:`here <guides/specifying-dependencies:Specifying Dependencies>`.
 
 
-Upgrade your custom theme to be compatible with newer mkdocs versions
+Upgrade your custom theme to be compatible with later MkDocs versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is possible that event your build passes your documentation doesn't look correct.
-This may be because the new ``mkdocs==0.17.3`` version installed by Read the Docs introduced some breaking changes on the structure of the theme.
+It is possible that your build passes but your documentation doesn't look correct.
+This may be because newer MkDocs versions installed by Read the Docs introduced some breaking changes on the structure of the theme.
 
 You should check the `mkdocs' Custom Theme documentation`_ to upgrade your custom theme and make it compatible with the new version.
 
@@ -51,7 +46,7 @@ You should check the `mkdocs' Custom Theme documentation`_ to upgrade your custo
 Upgrade how extension arguments are defined
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``mkdocs`` has changed the way that ``markdown_extensions`` are defined and you may need to upgrade it.
+MkDocs has changed the way that ``markdown_extensions`` are defined and you may need to upgrade it.
 If you where passing arguments to the extension by defining them between brackets (``toc(permalink=true)``) in your ``mkdocs.yaml`` you may need to upgrade it to the new way.
 
 For example, this definition:

docs/guides/pdf-non-ascii-languages.rst

@@ -1,8 +1,8 @@
-Build PDF format for non-ASCII languages
-========================================
+Sphinx PDFs with Unicode
+========================
 
-Sphinx offers different `LaTeX engines`_ that support Unicode characters and non-ASCII languages,
-like Japanese or Chinese.
+Sphinx offers different `LaTeX engines`_ that have better support for Unicode characters
+and non-European languages like Japanese or Chinese.
 By default Sphinx uses ``pdflatex``,
 which does not have good support for Unicode characters and may make the PDF builder fail.