MAINT: Switch to sphinx-theme-builder (#469)

.github/workflows/tests.yml

@@ -21,11 +21,11 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
         sphinx: [">=3,<4", ">=4,<5"]
         include:
         - os: windows-latest
-          python-version: 3.7
+          python-version: 3.9
           sphinx: ">=3,<4"
         - os: macos-latest
           python-version: 3.9
@@ -38,14 +38,18 @@ jobs:
       uses: actions/setup-python@v2
       with:
         python-version: ${{ matrix.python-version }}
+        cache: "pip"
+        cache-dependency-path: "pyproject.toml"
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[testing]
+        python -m pip install -e .[test]
+
     - name: Run pytest
       run: >
         pytest --durations=10 --cov=sphinx_book_theme --cov-report=xml --cov-report=term-missing
+
     - name: Upload to Codecov
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.7 && github.repository == 'executablebooks/sphinx-book-theme'
       uses: codecov/codecov-action@v1
@@ -68,7 +72,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[sphinx]
+        pip install -e .[doc]
     - name: Build documentation
       run: >
         sphinx-build -b html docs docs/_build/html -w warnings.txt
@@ -107,11 +111,10 @@ jobs:
         with:
           python-version: 3.7
 
-      - name: Install build dependecies
-        run: pip install wheel
-
       - name: Build package
-        run: python setup.py sdist bdist_wheel
+        run: |
+          python -m pip install -U pip build
+          python -m build
 
       - name: Publish
         uses: pypa/[email protected]

.gitignore

@@ -25,7 +25,6 @@ share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
-MANIFEST
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -40,7 +39,6 @@ pip-delete-this-directory.txt
 # Unit test / coverage reports
 htmlcov/
 .tox/
-.nox/
 .coverage
 .coverage.*
 .cache
@@ -132,5 +130,10 @@ dmypy.json
 # mac OS
 .DS_Store
 
-# VS Code
+# nodejs
+.nodeenv/
+node_modules/
+
+# Editors
 .vscode/
+.idea

.pre-commit-config.yaml

@@ -5,12 +5,12 @@ exclude: >
     (?x)^(
       \.vscode/settings\.json|
     )$
-
 repos:
 
   - repo: git://github.com/pre-commit/pre-commit-hooks
     rev: v4.1.0
     hooks:
+    - id: check-toml
     - id: check-json
     - id: check-yaml
     - id: end-of-file-fixer
@@ -25,20 +25,3 @@ repos:
     rev: 21.12b0
     hooks:
     - id: black
-
-  - repo: https://github.com/mgedmin/check-manifest
-    rev: "0.47"
-    hooks:
-    - id: check-manifest
-
-  - repo: https://github.com/executablebooks/web-compile
-    rev: v0.2.2
-    hooks:
-      - id: web-compile
-        files: >-
-            (?x)^(
-                web-compile-config.yml|
-                src/.*|
-                sphinx_book_theme/static/.*|
-                sphinx_book_theme/theme.conf
-            )$

.readthedocs.yml

@@ -3,10 +3,8 @@ version: 2
 python:
   version: 3
   install:
-      - method: pip
-        path: .
-        extra_requirements:
-          - sphinx
+    - method: pip
+      path: .[doc]
 
 sphinx:
   builder: html

docs/conf.py

@@ -100,7 +100,6 @@
 }
 
 html_theme_options = {
-    "theme_dev_mode": True,
     "path_to_docs": "docs",
     "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
     # "repository_branch": "gh-pages",  # For testing

docs/contributing.md

@@ -11,15 +11,11 @@ project.
 
 ## Repository structure
 
-This repository is a split into a few critical folders:
+This theme uses [sphinx-theme-builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) as its build backend, and follows the [filesystem layout](https://sphinx-theme-builder.readthedocs.io/en/latest/reference/filesystem-layout/) recommended by it.
+On top of that, it has the following additional critical files/folders:
 
-`sphinx-book-theme/`
-: The Sphinx extension package, containing the Python code, Jinja templates and (compiled) assets (HTML/CSS/JS etc).
-: These are used to generate the HTML page for every file in your site whenever the site is built using Sphinx.
-: **NOTE**: Do not alter the compiled CSS/JS directly (alter in `src/`).
-
-`src/`
-: Contains the source SCSS and JS, which will be compiled and written to `sphinx-book-theme/static`, as configured by `web-compile-config.yml` (see [executablebooks/web-compile](https://github.com/executablebooks/web-compile) for details).
+`webpack.config.js`
+: Contains the compilation code to convert source files like SCSS and JS in `src/sphinx_book_theme/assets/*` into the production assets in `src/sphinx_book_theme/theme/sphinx_book_theme/static/` .
 : This compilation is called by default, during development commands (see below).
 
 `docs/`
@@ -49,7 +45,7 @@ This repository is a split into a few critical folders:
    cd sphinx-book-theme
    ```
 
-2. Ensure you have Python 3.6 or newer!
+2. Ensure you have Python 3.7 or newer!
 3. Install `tox`.
    `tox` is a tool for managing virtual environments for test suites or common jobs that are run with a repository.
    It ensures that your environment is consistent each time you build the docs.
@@ -88,26 +84,38 @@ This repository is a split into a few critical folders:
    ```
    :::
 
+## Compile the CSS/JS assets
+
+The source files for CSS and JS assets are in `src/sphinx_book_theme/assets`. The `sphinx-theme-builder` package automates the compilation of web assets.
+These are then built and bundled with the theme (e.g., `scss` is turned into `css`).
+
+To compile the CSS/JS assets with `tox`, run the following command:
+
+```console
+$ tox -s compile
+```
+
+This will compile all assets and place them in the appropriate folder to be used with documentation builds.
+
+```{note}
+Compiled assets are **not committed to git**.
+The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to git history.
+```
 
 ## Preview changes you make to the theme
 
 The easiest way to preview the changes you make to this theme is by building the documentation of this theme locally using `tox`.
 
 To do so, follow these steps:
 
-1. **Make your changes in `src/`**. This folder contains all of the SCSS and Javascript that are used in this site. You should edit the files here, and they will be built and included with the site in the `sphinx_book_theme/` folder at build time.
-2. **Install `tox`**.
-
-   ```console
-   $ pip install tox
-   ```
-3. **Build the documentation**. You can use the following `tox` command:
+1. **Make your changes in `src/sphinx_book_theme/assets/`**. This folder contains all of the SCSS and Javascript that are used in this site. You should edit the files here, and they will be built and included with the site in the `sphinx_book_theme/` folder at build time.
+2. **Build the documentation**. You can use the following `tox` command:
 
    ```console
    $ tox -e docs-update
    ```
 
-This will build the documentation using the latest version of the theme (including any changes you've made to the `src/` folder) and put the outputs in `docs/_build/html`.
+This will build the documentation using the latest version of the theme (including any changes you've made to the `src/sphinx_book_theme/assets/*` folder) and put the outputs in `docs/_build/html`.
 You may then preview them by opening one of the HTML files.
 
 ### Auto-build the docs when you make changes
@@ -123,22 +131,12 @@ $ tox -e docs-live
 This will do the following:
 
 - Generate the theme's documentation (similar to running `tox -e docs-update`)
-- Start a development server on an available port `localhost:xxxx`
+- Start a development server on an available port `127.0.0.1:xxxx`
 - Open it in your default browser
 - Watch for changes and automagically regenerate the documentation and auto-reload your browser when a change is made.
 
 With this, you can modify the theme in an editor, and see how those modifications render on the browser.
 
-### Use different Sphinx builders
-
-When building documentation locally, you may use different Sphinx builders by providing them as arguments to `tox`.
-For example:
-
-```console
-$ tox -e docs-update -- singlehtml
-$ tox -e docs-live -- singlehtml
-```
-
 ## Run Tests
 
 This theme has a test suite to ensure that all the relevant user content is
@@ -151,14 +149,14 @@ $ tox
 You can also run against different Python and sphinx versions, and supply arguments to pytest:
 
 ```console
-$ tox -e py38-sphinx2 -- -x
+$ tox -e py38-sphinx3 -- -x
 ```
 
 :::{tip}
 To "re-build" an environment, wih updated dependancy versions, use:
 
 ```console
-$ tox -r -e py38-sphinx2
+$ tox -r -e py38-sphinx3
 ```
 
 :::

docs/customize/index.md

@@ -57,9 +57,6 @@ The following options are available via `html_theme_options`
 * - `toc_title`
   - str
   - The text to be displayed with the in-page TOC (`Contents` is default)
-* - `theme_dev_mode`
-  - bool
-  - (developers only) Trigger some features that make it easier to develop the theme.
 ```
 
 ## Customization Topics

package.json

@@ -0,0 +1,24 @@
+{
+  "name": "sphinx_book_theme",
+  "repository": "https://github.com/executablebooks/sphinx-book-theme",
+  "scripts": {
+    "build": "webpack"
+  },
+  "devDependencies": {
+    "css-loader": "^3.4.2",
+    "dedent": "^0.7.0",
+    "extract-loader": "^4.0.3",
+    "file-loader": "^5.0.2",
+    "html-webpack-plugin": "^4.3.0",
+    "node-sass": "^6.0.1",
+    "optimize-css-assets-webpack-plugin": "^5.0.3",
+    "sass-loader": "^10.1.1",
+    "style-loader": "^1.1.3",
+    "webpack": "^4.41.6",
+    "webpack-cli": "^3.3.11",
+    "webpack-dev-server": "^3.10.3"
+  },
+  "dependencies": {
+    "optimize-css-assets-webpack-plugin": "^5.0.3"
+  }
+}