Merge pull request #201 from dgarcia360/branch-1.0

Add Scylla Sphinx Theme 1.0

Author: lauranovich

.babelrc.json

@@ -0,0 +1,4 @@
+{
+  "presets": ["@babel/preset-env"],
+  "plugins": ["@babel/plugin-proposal-class-properties"]
+}

.github/workflows/[email protected]

@@ -0,0 +1,31 @@
+name: "Publish docs to GitHub Pages"
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.7
+      - name: Build docs
+        run: |
+          export PATH=$PATH:~/.local/bin
+          cd docs
+          make multiversion
+      - name: Deploy
+        run: ./docs/_utils/deploy.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/[email protected]

@@ -0,0 +1,28 @@
+name: "Build docs on pull requests"
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.7
+      - name: Build docs
+        run: |
+          export PATH=$PATH:~/.local/bin
+          cd docs
+          make test

.github/workflows/pages.yml

@@ -173,7 +173,6 @@ ipython_config.py
 
 # pyenv
 .python-version
-poetry.lock
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
 #   However, in case of collaboration, if having platform-specific dependencies or dependencies
@@ -213,4 +212,3 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
-

.gitignore

@@ -0,0 +1,7 @@
+module.exports = {
+  plugins: {
+    "postcss-preset-env": {
+      browsers: "last 2 versions",
+    },
+  },
+};

.postcss.config.js

@@ -0,0 +1,31 @@
+repos:
+  - repo: local
+    hooks:
+      - id: build-assets
+        name: build-assets
+        entry: npm run
+        args: ["build"]
+        language: system
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v2.3.0
+    hooks:
+      - id: prettier
+
+  - repo: https://github.com/psf/black
+    rev: 21.5b1
+    hooks:
+      - id: black
+
+  - repo: git://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-yaml
+      - id: end-of-file-fixer
+        exclude: "sphinx_scylladb_theme/static"
+      - id: forbid-new-submodules
+      - id: trailing-whitespace

.pre-commit-config.yaml

@@ -0,0 +1 @@
+sphinx_scylladb_theme/static

.prettierignore

@@ -5,12 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.25] - 05 July 2021
+## [1.0] - 01 September 2021
+
+### Added
+
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): We’ve made a number of updates to the look and feel of the theme to improve the overall user experience.
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): The static front end files (CSS, JS, and images) are now managed with `webpack`. For more information, see [Contribute to the Theme](https://sphinx-theme.scylladb.com/stable/contribute/contribute-theme.html).
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): The promo banner now supports icons with the option theme option `banner_icon_path`. For more information, see [Template Options](https://sphinx-theme.scylladb.com/stable/configuration/template.html).
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): The contribute button adds the option "Edit on GitHub". To configure your project to support this option, read [Template Options](https://sphinx-theme.scylladb.com/stable/configuration/template.html).
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): We run hooks on every commit to automatically point out linting issues.
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): The new workflow `docs-pr` runs on pull requests to make sure docs build without warnings before being merged. For more information, see [Deployment](https://sphinx-theme.scylladb.com/stable/github-pages.html).
+
+### Changed
+
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): Topics boxes (cards) can be used in other sections, and not just on the home page. We now have different layouts to suit most projects' needs. Check them out at [Topic Boxes](https://sphinx-theme.scylladb.com/stable/examples/topic-box)
 
 ### Fixed
 
-- [#171](https://github.com/scylladb/sphinx-scylladb-theme/pull/194): FontAwesome 5.0 backwards compatibility.
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): We've added more unit tests to the project, especially to extensions.
+- [#201](https://github.com/scylladb/sphinx-scylladb-theme/pull/201): We've fixed JavaScript warnings and errors raised by the console.
 
+## [0.1.25] - 05 July 2021
+
+### Fixed
+
+- [#194](https://github.com/scylladb/sphinx-scylladb-theme/pull/194): FontAwesome 5.0 backwards compatibility.
 
 ## [0.1.24] - 17 June 2021
 
@@ -52,20 +71,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): ``smv_rename_latest_version`` setting in ``conf.py`` overrides the latest version output directory.
+- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): `smv_rename_latest_version` setting in `conf.py` overrides the latest version output directory.
 
 ### Changed
 
-- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): Moved ``smv_latest_version`` from ``github/workflows/pages.yml`` to ``conf.py``.
+- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): Moved `smv_latest_version` from `github/workflows/pages.yml` to `conf.py`.
 
 ### Removed
 
-- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): ``_utils/redirects.sh`` script.
+- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): `_utils/redirects.sh` script.
 
 ### Fixed
 
-- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): ``make multiversionpreview`` was not redirecting automatically to the latest version.
-
+- [#121](https://github.com/scylladb/sphinx-scylladb-theme/issues/121): `make multiversionpreview` was not redirecting automatically to the latest version.
 
 ## [0.1.20] - 19 Jan 2021
 
@@ -92,7 +110,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - [#103](https://github.com/scylladb/sphinx-scylladb-theme/issues/103): Report button does not break when the page title has inlines.
 
-
 ## [0.1.18] - 31 Dec 2020
 
 ### Added
@@ -112,7 +129,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - [#83](https://github.com/scylladb/sphinx-scylladb-theme/issues/83): Copyright year in the footer is now updated automatically.
 
-
 ## [0.1.15] - 17 Nov 2020
 
 ### Added
@@ -152,6 +168,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [#59](https://github.com/scylladb/sphinx-scylladb-theme/issues/59): All projects now share a 404 page.
 - [#58](https://github.com/scylladb/sphinx-scylladb-theme/issues/58): Support for redirections.
 
+[1.0]: https://github.com/scylladb/sphinx-scylladb-theme/compare/0.1.25...1.0.4
 [0.1.25]: https://github.com/scylladb/sphinx-scylladb-theme/compare/0.1.24...0.1.25
 [0.1.24]: https://github.com/scylladb/sphinx-scylladb-theme/compare/0.1.23...0.1.24
 [0.1.23]: https://github.com/scylladb/sphinx-scylladb-theme/compare/0.1.22...0.1.23

CHANGELOG.md

@@ -1,7 +1,7 @@
-==========================
-Scylla Documentation Theme
-==========================
+===================
+Scylla Sphinx Theme
+===================
 
-Sphinx theme for ScyllaDB documentation projects.
+Sphinx theme for Scylla documentation projects.
 
 `Read More: <https://github.com/scylladb/sphinx-scylladb-theme>`_

PYPI.rst

@@ -1,8 +1,8 @@
-=====================
-Sphinx ScyllaDB Theme
-=====================
+===================
+Scylla Sphinx Theme
+===================
 
-Sphinx theme for ScyllaDB documentation projects.
+Sphinx theme for Scylla documentation projects.
 
 The theme is available as a `PyPI <https://pypi.org/project/sphinx-scylladb-theme/>`_ package, and has been tested with Python 3.7, Sphinx 2.4.4 and Fedora 32.
 
@@ -11,7 +11,7 @@ Features
 
 **Shared Design**
 
-All ScyllaDB documentation sites share a common look and feel.
+All Scylla documentation sites share a common look and feel.
 
 **Multiversion Support**
 

README.rst

@@ -0,0 +1,12 @@
+const path = require("path");
+
+module.exports = {
+  // Source files
+  src: path.resolve(__dirname, "../src"),
+
+  // Production build files
+  build: path.resolve(__dirname, "../sphinx_scylladb_theme/static"),
+
+  // Static files that get copied to build folder
+  public: path.resolve(__dirname, "../src/img"),
+};

config/paths.js

@@ -0,0 +1,66 @@
+const { CleanWebpackPlugin } = require("clean-webpack-plugin");
+const CopyWebpackPlugin = require("copy-webpack-plugin");
+const PrettierPlugin = require("prettier-webpack-plugin");
+const ESLintPlugin = require("eslint-webpack-plugin");
+const webpack = require("webpack");
+const paths = require("./paths");
+
+module.exports = {
+  // Where webpack looks to start building the bundle
+  entry: [paths.src + "/js/index.js"],
+
+  // Where webpack outputs the assets and bundles
+  output: {
+    path: paths.build,
+    filename: "[name].js?[hash]",
+  },
+
+  // Customize the webpack build process
+  plugins: [
+    // Removes/cleans build folders and unused assets when rebuilding
+    new CleanWebpackPlugin(),
+
+    // Copies files from target to destination folder
+    new CopyWebpackPlugin({
+      patterns: [
+        {
+          from: paths.public,
+          to: "img",
+          globOptions: {
+            ignore: ["*.DS_Store"],
+          },
+          noErrorOnMissing: true,
+        },
+      ],
+    }),
+
+    // ESLint configuration
+    new ESLintPlugin({
+      files: [".", "config"],
+      formatter: "table",
+    }),
+
+    // Prettier configuration
+    new PrettierPlugin(),
+
+    // Prettier configuration
+    new webpack.ProvidePlugin({
+      $: "jquery",
+      jQuery: "jquery",
+    }),
+  ],
+
+  // Determine how modules within the project are treated
+  module: {
+    rules: [
+      // JavaScript: Use Babel to transpile JavaScript files
+      { test: /\.js$/, use: ["babel-loader"] },
+
+      // Images: Copy image files to build folder
+      { test: /\.(?:ico|gif|png|jpg|jpeg)$/i, type: "asset/resource" },
+
+      // Fonts and SVGs: Inline files
+      { test: /\.(woff(2)?|eot|ttf|otf|svg|)$/, type: "asset/inline" },
+    ],
+  },
+};

config/webpack.common.js

@@ -0,0 +1,45 @@
+const webpack = require("webpack");
+const { merge } = require("webpack-merge");
+const common = require("./webpack.common.js");
+const paths = require("./paths");
+
+module.exports = merge(common, {
+  // Set the mode to development or production
+  mode: "development",
+
+  // Control how source maps are generated
+  devtool: "inline-source-map",
+
+  // Spin up a server for quick development
+  devServer: {
+    historyApiFallback: true,
+    contentBase: paths.build,
+    open: true,
+    compress: true,
+    hot: true,
+    port: 8080,
+  },
+
+  module: {
+    rules: [
+      // Styles: Inject CSS into the head with source maps
+      {
+        test: /\.(scss|css)$/,
+        use: [
+          "style-loader",
+          {
+            loader: "css-loader",
+            options: { sourceMap: true, importLoaders: 1, modules: true },
+          },
+          { loader: "postcss-loader", options: { sourceMap: true } },
+          { loader: "sass-loader", options: { sourceMap: true } },
+        ],
+      },
+    ],
+  },
+
+  plugins: [
+    // Only update what has changed on hot reload
+    new webpack.HotModuleReplacementPlugin(),
+  ],
+});