Document BS2 deprication/BS5 migration (#237)

admin-manual/customization/theming.rst

@@ -4,16 +4,22 @@
 Theming
 =======
 
-AtoM themes can be customized by editing the appropriate css and .php files, or
-you can create a custom theme.
+AtoM themes can be customized by editing the appropriate css/scss and .php files,
+or you can create a custom theme.
 
 Please note AtoM 2.7 introduced a new version of the Bootstrap (“BS5”) web
-framework, and shipped with a theme based on BS5. Creating a custom theme using
-BS5 is slightly different than documented below (which was written using the
-original BS2 framework provided in previous versions of AtoM). This
-documentation will be updated, but in the meantime it is still possible to
-create a custom theme using BS2 using the instructions below.
+framework, and shipped with a theme based on BS5.
 
+Bootstrap 2 Deprecation Notice
+------------------------------
+
+Bootstrap 2 themes have been deprecated and will be removed in a future release.
+Please consider switching to a Bootstrap 5 theme.
+
+.. SEEALSO::
+
+   * :ref:`Change theme <themes-change-theme>`
+   * :ref:`Create a custom theme <customization-custom-theme>`
 
 Customize how an AtoM theme looks
 ---------------------------------
@@ -54,23 +60,124 @@ don't have to get your hands too dirty. It's in the details where most of the
 complexities are found. Dominion is the result of a cyclic process of testing
 and refining by a large community of users, try not to underestimate that!
 
-AtoM bundles two themes: arDominionPlugin and arArchivesCanadaPlugin. Their
-names follow the naming convention of Symfony 1.x plugins, because that is how
-themes are implemented in AtoM. You may want to read more about Symfony plugins
+AtoM bundles three themes: arDominionPlugin, arDominionB5Plugin and arArchivesCanadaPlugin.
+Their names follow the naming convention of Symfony 1.x plugins, because that is
+how themes are implemented in AtoM. You may want to read more about Symfony plugins
 later following `one of their guides <http://symfony.com/legacy/doc/gentle-introduction/1_4/en/17-Extending-Symfony#chapter_17_plug_ins>`_.
 
-arDominionPlugin is the default theme, i.e. the theme that will be used in a
+arDominionB5Plugin is the default theme, i.e. the theme that will be used in a
 fresh installation. arArchivesCanadaPlugin was developed as an extension of the
 former and the following instructions will show you how to create your custom
 theme as we did with arArchivesCanadaPlugin.
 
-Assuming that you already have AtoM installed in your development environment
-(you can use our :ref:`Vagrant box <dev-env-vagrant>`), let's start
-building the plugin structure from the command line. Our theme is going to be
-called Corcovado (arCorcovadoPlugin). We are going to track its contents with
-git and publish them in a remote repository hosted by GitHub so we can enable
-others to contribute in the development. The repository is open source so you
-can use it for your own reference, see https://github.com/artefactual-labs/atom-theme-corcovado.
+.. TIP::
+
+   The following instructions assume you already have an AtoM development environment set up
+   locally. If not, we have two development-friendly environments for AtoM - see:
+
+   * :ref:`dev-env-vagrant`
+   * :ref:`dev-env-compose`
+
+++++++++++++++++++++++++
+Custom Bootstrap 5 Theme
+++++++++++++++++++++++++
+
+With the new BS5 framework, creating a custom theme that is an extension
+of the default arDominionB5Plugin theme has become significantly easier. A
+skeleton for an empty AtoM theme plugin that extends arDominionB5Plugin without
+any modifications can be found in this `arThemeB5Plugin repository
+<https://github.com/artefactual-labs/arThemeB5Plugin>`_.
+
+Additional steps for tarball installations:
+*******************************************
+
+If not already installed, first `download the node.js binary distributuion
+<https://nodejs.org/en/download>`_ and export the PATH variable.
+
+The tarball is missing three required files for this:
+
+* :version-ref:`package.json<https://github.com/artefactual/atom/blob/stable/{version}.x/package.json>`
+* :version-ref:`package-lock.json<https://github.com/artefactual/atom/blob/stable/{version}.x/package-lock.json>`
+* :version-ref:`webpack.config.js <https://github.com/artefactual/atom/blob/stable/{version}.x/webpack.config.js>`
+
+Copy the above files from the *correct stable branch*
+(stable/|version|.x for AtoM |version|) of our `AtoM repo <https://github.com/artefactual/atom/>`_.
+
+Test that everything has been installed correctly:
+
+.. code-block:: bash
+
+   $ npm install
+   $ npm run build
+
+If you encounter any issues at this point, we recommend resolving any issues by
+consulting the :ref:`maintenance-troubleshooting` documentation before continuing.
+
+Let's begin creating our new BS5 Theme:
+***************************************
+
+.. code-block:: bash
+
+   $ cd ~/atom
+   $ git clone --depth=1 https://github.com/artefactual-labs/arThemeB5Plugin.git plugins/arCustomThemeB5Plugin
+   $ rm -rf plugins/arThemeB5Plugin/.git plugins/arB5ThemePlugin/README.md
+
+Here, we've cloned the repo directly into the `atom/plugins` directory, renaming
+the theme to `arCustomThemeB5Plugin`, and removed the git related files.
+
+.. code-block:: bash
+
+   $ cd plugins/arCustomThemeB5Plugin/config/
+   $ mv arThemeB5PluginConfiguration.class.php arCustomThemeB5PluginConfiguration.class.php
+
+To configure the theme plugin, we've renamed the config filename to match the
+plugin name. Next, we need to change the `class name <https://github.com/artefactual-labs/arThemeB5Plugin/blob/main/config/arThemeB5PluginConfiguration.class.php#L23>`_
+to match the new config filename (`arCustomThemeB5PluginConfiguration` for this
+example).
+
+Optionally, you can update the theme summary and version within the config file
+and change the theme image thumbnail by replacing `arCustomThemeB5Plugin/images/image.png`.
+
+To change the logo for BS5 themes, add the logo to `plugins/arCustomThemeB5Plugin/images/logo.png`.
+Style changes can be made directly to, or linked in, the `main SCSS file <https://github.com/artefactual-labs/arThemeB5Plugin/blob/main/scss/main.scss>`_.
+Custom javascripts can be added to the js directory and linked in the `main js file <https://github.com/artefactual-labs/arThemeB5Plugin/blob/main/js/main.js>`_.
+
+For additional functionlity modifications, copy files required into the new `plugins/arCustomThemeB5Plugin`
+directory for overwriting. Due to file precedence, when copying files, first
+check the `plugins/arDominionB5Plugin` for the required file, and only copy from
+`apps/qubit` when the file is not found in `plugins/arDominionB5Plugin`. Files
+copied should have the same file path with `plugin/arCustomThemeB5Plugin` replacing
+`apps/qubit` or `plugins/arDominionB5Plugin`.
+
+.. code-block:: bash
+
+   cd ~/atom
+   npm install
+   npm run build
+
+Once you've made all the required changes to your theme, build the theme assets,
+and you should now be able to use your new theme!
+
+.. TIP::
+
+   If you are still not seeing your changes take effect, remember to
+   :ref:`clear the Symfony cache <maintenance-clear-cache>` and your
+   web browser's cache as well!
+
+++++++++++++++++++++++++
+Custom Bootstrap 2 Theme
+++++++++++++++++++++++++
+
+.. NOTE::
+
+   Bootstrap 2 themes have been deprecated and will be removed in a future
+   release. Please consider switching to a Bootstrap 5 theme.
+
+Let's start building the plugin structure from the command line. Our theme is
+going to be called Corcovado (arCorcovadoPlugin). We are going to track its
+contents with git and publish them in a remote repository hosted by GitHub so we
+can enable others to contribute in the development. The repository is open source
+so you can use it for your own reference, see https://github.com/artefactual-labs/atom-theme-corcovado.
 You can also `create your own repository <https://help.github.com/articles/create-a-repo/>`_.
 
 Let's begin to do some real work:

admin-manual/installation/ubuntu.rst

@@ -301,6 +301,17 @@ For development environments, the dev libraries should also be installed:
 
 After downloading the code, you will need to compile the themes files:
 
+Compile Bootstrap 5 Theme Files:
+********************************
+
+.. code-block:: bash
+
+   sudo npm install
+   sudo npm run build
+
+Compile Bootstrap 2 Theme Files:
+********************************
+
 .. code-block:: bash
 
    sudo apt install npm make
@@ -766,9 +777,16 @@ use. You can access it by entering your base URL into a web browser - the
 configuring the installer. See :ref:`getting-started-all` for further
 information on your first steps using AtoM.
 
-If you encounter any issues, we recommend consulting the
-:ref:`maintenance-troubleshooting` documentation for suggestions on how to
-resolve common errors.
+.. TIP::
+
+   After implementing the above changes during the initial setup, you might need
+   to :ref:`clear the cache <maintenance-clear-cache>` and
+   :ref:`restart PHP-FPM <troubleshooting-restart-php-fpm>` for the changes to
+   take effect.
+
+   If you encounter any other issues, we recommend consulting the
+   :ref:`maintenance-troubleshooting` documentation for suggestions on how to
+   resolve common errors.
 
 :ref:`Back to top <installation-ubuntu>`
 

admin-manual/installation/upgrading.rst

@@ -368,9 +368,60 @@ Upgrading with a custom theme plugin
 If you have developed a custom theme plugin for your application (for more
 information, see :ref:`customization-custom-theme`), you may need to perform
 an additional step following an upgrade to ensure that all pages are styled
-correctly. Please note that the instructions below are for upgrading a custom
-theme that continues to the Bootstrap 2 (“BS2”). Documentation for upgrading to
-BS5 will be provided at a later date.
+correctly.
+
++++++++++++
+Bootstrap 5
++++++++++++
+
+Additional steps for tarball installations:
+*******************************************
+
+If not already installed, first `download the node.js binary distributuion
+<https://nodejs.org/en/download>`_ and export the PATH variable.
+
+The tarball is missing three required files for this:
+
+* :version-ref:`package.json<https://github.com/artefactual/atom/blob/stable/{version}.x/package.json>`
+* :version-ref:`package-lock.json<https://github.com/artefactual/atom/blob/stable/{version}.x/package-lock.json>`
+* :version-ref:`webpack.config.js <https://github.com/artefactual/atom/blob/stable/{version}.x/webpack.config.js>`
+
+Copy the above files from the *correct stable branch*
+(stable/|version|.x for AtoM |version|) of our `AtoM repo <https://github.com/artefactual/atom/>`_.
+
+Test that everything has been installed correctly:
+
+.. code-block:: bash
+
+   $ npm install
+   $ npm run build
+
+If you encounter any issues at this point, we recommend resolving them by
+consulting the :ref:`maintenance-troubleshooting` documentation before continuing.
+
+Rebuild BS5 theme assets:
+*************************
+
+.. code-block:: bash
+
+   cd ~/atom
+   npm install
+   npm run build
+
+.. TIP::
+
+   If you are still not seeing your changes take effect, remember to
+   :ref:`clear the Symfony cache <maintenance-clear-cache>` and your
+   web browser's cache as well!
+
++++++++++++
+Bootstrap 2
++++++++++++
+
+.. NOTE::
+
+   Bootstrap 2 themes have been deprecated and will be removed in a future
+   release. Please consider switching to a Bootstrap 5 theme.
 
 Specifically, :ref:`job-details` may not appear properly styled in a custom
 theme without an additional step. To ensure your Jobs pages properly inherit
@@ -413,10 +464,10 @@ Specifically, your modified files should be updated to match these lines:
   <https://github.com/artefactual/atom/blob/HEAD/apps/qubit/modules/staticpage/templates/homeSuccess.php#L28>`__
 
 Recompiling after making modifications
---------------------------------------
+======================================
 
 After making any necessary updates to your custom theme, you should rebuild
-the CSS for the custom themeplugin, using the ``make`` command. Here is an
+the CSS for the custom theme plugin, using the ``make`` command. Here is an
 example of rebuilding the CSS for the ArchivesCanada theme - you can swap in
 the name of your plugin:
 

conf.py

@@ -71,9 +71,11 @@
 # built documents.
 #
 # The short X.Y version.
-version = "2.7"
+# version = "2.7"
 # The full version, including alpha/beta/rc tags.
 release = "2.7.3"
+version = '.'.join(release.split('.')[:2])
+extensions = ['sphinx_version_ref']
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

user-manual/administer/themes.rst

@@ -15,27 +15,32 @@ This section describes how to change the theme, :term:`site title`,
 
 .. _themes-change-theme:
 
+.. IMPORTANT::
+
+   Bootstrap 2 themes have been deprecated and will be removed in a future
+   release. Please consider switching to a Bootstrap 5 theme.
+
 Change theme
 ============
 
-AtoM 2.7 ships with 3 themes: the default :term:`Dominion theme`
-(arDominionPlugin) and the Archives Canada theme (arArchivesCanadaPlugin).
+AtoM 2.7 and up ships with 3 themes: the default :term:`Dominion theme`
+(arDominionB5Plugin) and the Archives Canada theme (arArchivesCanadaPlugin).
 
 The Dominion themes are grey, white and black with the AtoM logo. The Archives
 Canada theme is yellow, blue and white with the ArchivesCanada logo (see images
 below).
 
-The new version of the Dominion theme is based on Bootstrap 5 (“BS5”), a
+The default version of the Dominion theme is based on Bootstrap 5 (“BS5”), a
 framework for developing websites. BS5 provides a number of improvements over
 the previous version (“BS2”) such as better security, responsiveness and
 accessibility.
 
-If you’re a brand new AtoM user, we suggest that you use the BS5 theme. If you
-are performing an upgrade to 2.7 from an older version, and you have a custom
-theme, we recommend you continue to use BS2 at this time.
+If you’re a brand new AtoM user, please use the default BS5 theme. If you
+are performing an upgrade from an older version, and you have a custom
+theme, we recommend upgrading that theme to use BS5.
 
 
-.. figure:: images/dominion-theme.*
+.. figure:: images/dominionB5-theme.*
    :align: center
    :figwidth: 60%
    :width: 100%
@@ -68,6 +73,10 @@ To change the theme:
 2. Click on the :term:`radio button` in the "Enabled" column for the theme
    you wish to have enabled and click "Save."
 
+.. SEEALSO::
+
+   * :ref:`Create a custom theme <customization-custom-theme>`
+
 .. _themes-add-remove-elements:
 
 Add or remove elements