Merge pull request #246 from openedx/feanil/theme_migration_how_to

docs: Add a basic how-to for switching to the new theme.

source/developers/how-tos/switch-to-the-sphinx-book-theme.rst

@@ -0,0 +1,117 @@
+How to Switch to the sphinx-book-theme for Documentation
+########################################################
+
+This how-to will help you switch from your existing Sphinx theme to the
+sphinx-book-theme for a sphinx documentation project.
+
+Assumptions
+***********
+
+.. This section should contain a bulleted list of assumptions you have of the
+   person who is following the How-to.  The assumptions may link to other
+   how-tos if possible.
+
+* You already have a Sphinx documentation project.
+
+* You know how to work with Python code.
+
+Steps
+*****
+
+.. A task should have 3 - 7 steps.  Tasks with more should be broken down into digestible chunks.
+
+#. Update and rebuild your requirements.
+
+   #. Find the requirements file that has your documentation requirements in it.
+
+      For most projects there will be a ``requirements/docs.in`` file which will
+      contain your theme as a Python requirement.  For example if you are using
+      the deprecated ``edx-sphinx-theme``, you'll see a line with that package
+      name on it.
+
+   #. Remove your old theme (for example, ``edx-sphinx-theme``) and add a line for the
+      ``sphinx-book-theme``.
+
+      .. code::
+
+         - edx-sphinx-theme
+         + sphinx-book-theme
+
+   #. Run ``make upgrade``
+
+   #. Install your doc requirements.
+
+      .. code::
+
+         pip install -r requirements/docs.txt # in most cases
+
+#. Update conf.py
+
+   Add or update the following
+   .. code::
+
+      import os
+
+      html_theme_options = {
+
+          "repository_url": TODO: Add a github URL Here, for example https://github.com/openedx/repo-name,
+          "repository_branch": TODO: Add the correct branch, for example 'main',
+          "path_to_docs": "docs/",
+          "logo_only": True,
+          "home_page_in_toc": True,
+          "use_repository_button": True,
+          "use_issues_button": True,
+          "use_edit_page_button": True,
+          # Please don't change unless you know what you're doing.
+          "extra_footer": """
+              <a rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/">
+                  <img
+                      alt="Creative Commons License"
+                      style="border-width:0"
+                      src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"/>
+              </a>
+              <br>
+              These works by
+                  <a
+                      xmlns:cc="https://creativecommons.org/ns#"
+                      href="https://openedx.org"
+                      property="cc:attributionName"
+                      rel="cc:attributionURL"
+                  >The Center for Reimagining Learning</a>
+              are licensed under a
+                  <a
+                      rel="license"
+                      href="https://creativecommons.org/licenses/by-sa/4.0/"
+                  >Creative Commons Attribution-ShareAlike 4.0 International License</a>.
+          """
+      }
+
+      # Note the logo won't show up properly yet because there is an upstream
+      # bug in the theme that needs to be fixed first.
+      # If you'd like you can temporarily copy the logo file to your `_static`
+      # directory.
+      html_logo = "https://logos.openedx.org/open-edx-logo-color.png"
+      html_favicon = "https://logos.openedx.org/open-edx-favicon.ico"
+
+      # Set the DJANGO_SETTINGS_MODULE if it's not set.
+      # Only if your project has a dependency on Django
+      if not os.environ.get('DJANGO_SETTINGS_MODULE'):
+         # If you do depend on django you'll need a settings file that you can
+         # use when building docs.  This will allow you to pull docstrings from
+         # your code.
+         os.environ['DJANGO_SETTINGS_MODULE'] = 'test_utils.test_settings'
+
+#. Re-build your project and fix any errors.
+
+   .. code::
+
+      make html # and fix errors until there are no errors.
+
+Once everything is building correctly without errors you should be all set to
+make a pull request with your changes!
+
+.. Following the steps, you should add the result and any follow-up tasks needed.
+
+.. seealso::
+
+  :doc:`add-sphinx-docs-to-a-repo`