docs: update

kai687 · May 30, 2024 · 52e4ca7 · 52e4ca7
1 parent c7599a6
commit 52e4ca7
Show file tree

Hide file tree

Showing 21 changed files with 37 additions and 120 deletions.
diff --git a/README.md b/README.md
@@ -30,22 +30,14 @@
 
    For more information, see [Add your theme](https://sphinxawesome.xyz/how-to/add/).
 
-1. Recommended: add the bundled extension for more awesome code blocks:
-
-   ```python
-   # conf.py
-   extensions += ["sphinxawesome_theme.highlighting"]
-   ```
-
 ## Features
 
 With the Awesome Theme, you can build readable, functional, and beautiful documentation websites.
 
 ### Awesome code blocks
 
 - Code block have a **Copy** button for copying the code.
-- If you load the bundled `sphinxawesome_theme.highlighting`,
-  you can use these additional options in your `code-block` directives:
+- You can use these additional options in `code-block` directives:
 
   - `emphasize-added`. Highlight lines that should be added
   - `emphasize-removed`. Highlight lines that should be removed
@@ -57,5 +49,5 @@ Clicking the link icon after headers or captions automatically copies the URL to
 
 ### DocSearch
 
-This theme supports the [`sphinx-docsearch`](https://sphinx-docsearch.readthedocs.io/en/latest/) extension
+This theme supports the [`sphinx-docsearch`](https://sphinx-docsearch.readthedocs.io/) extension
 to replace the built-in search with Algolia DocSearch.
diff --git a/docs/about.rst b/docs/about.rst
@@ -30,7 +30,7 @@ The following table lists the assets used by the |product| to be awesome.
 +---------------------------------------------------------+-------------------------------+-----------------------------------------------------------------------------------+
 | Feature                                                 | Name/Website                  | License                                                                           |
 +=========================================================+===============================+===================================================================================+
-| UI design                                               | `shadcn/ui`_                  | `MIT License <https://github.com/shadcn/ui/blob/main/LICENSE.md>`__               |
+| UI design                                               | `shadcn/ui`_                  | `MIT License <https://github.com/shadcn-ui/ui/blob/main/LICENSE.md>`__            |
 +---------------------------------------------------------+-------------------------------+-----------------------------------------------------------------------------------+
 | CSS framework                                           | Tailwind_                     | `MIT License <https://github.com/tailwindlabs/tailwindcss/blob/master/LICENSE>`__ |
 +---------------------------------------------------------+-------------------------------+-----------------------------------------------------------------------------------+
@@ -64,8 +64,8 @@ The following table lists the assets used by the |product| to be awesome.
 .. _Material icons: https://fonts.google.com
 .. _undraw.co: https://undraw.co
 .. _custom: https://undraw.co/license
-.. _Primer/CSS: https://primer.style/css/
-.. _Entypo: http://www.entypo.com
+.. _Primer/CSS: https://primer.style/css/storybook/
+.. _Entypo: https://www.entypo.com
 .. _Zondicons: http://www.zondicons.com
 .. _Creative Commons Attribution-ShareAlike 4.0: https://creativecommons.org/licenses/by-sa/4.0/legalcode
 .. _Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0.html

diff --git a/docs/changelog/includes/5.0.rst b/docs/changelog/includes/5.0.rst
@@ -15,7 +15,6 @@ Dark mode
 Simpler setup
    You no longer need to load the theme as an extension.
    Like most other themes for Sphinx, it's enough to load it as ``html_theme``.
-   You can add the :ref:`sec:bundled-extensions` to enable more features.
 
 Redesign
    Using the design from `shadcn/ui <https://ui.shadcn.com/docs>`_.
@@ -56,7 +55,7 @@ You can remove them from your Sphinx configuration:
    such as captions or comments at the top of a code block.
    For code samples in multiple languages, you can use the ``sphinx-design`` extension with its ``tab-set-code`` directive.
 
-**DocSearch** is now an external extension, available as `sphinx-docsearch <https://sphinx-docsearch.readthedocs.io/en/latest/>`_.
+**DocSearch** is now an external extension, available as `sphinx-docsearch <https://sphinx-docsearch.readthedocs.io/>`_.
 
 ``html_awesome_docsearch``
    Load the bundled ``sphinxawesome_theme.docsearch`` extension instead.

diff --git a/docs/changelog/includes/5.2.rst b/docs/changelog/includes/5.2.rst
@@ -0,0 +1,5 @@
+Version 5.2
+-----------
+
+Version 5.2 of the |product| deprecates the bundled ``sphinxawesome_theme.highlighting`` extension.
+Its functionality is now integrated and this extension will be removed with version 6.
diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst
@@ -14,6 +14,7 @@ Changelog
 
 ----
 
+.. include:: includes/5.2.rst
 .. include:: includes/5.0.rst
 .. include:: includes/4.0.rst
 .. include:: includes/3.0.rst

diff --git a/docs/conf.py b/docs/conf.py
@@ -13,9 +13,6 @@
 
 load_dotenv()
 
-pygments_style = "emacs"
-pygments_style_dark = "github-dark"
-
 # -- Project information ---
 
 project = "Awesome Sphinx Theme"

diff --git a/docs/how-to/add/includes/add-to-sphinx.rst b/docs/how-to/add/includes/add-to-sphinx.rst
@@ -14,13 +14,11 @@ Add the theme to your Sphinx configuration
 
       :confval:`sphinx:html_theme`
 
-#. Recommended: add the bundled extension for better code blocks.
+#. Optional: load a bundled extension to check if you're using deprecated options:
 
    .. code-block:: python
       :caption: |conf|
 
       extensions += [
-         "sphinxawesome.highlighting",
-         # To help you with the upgrade to version 5:
-         # "sphinxawesome.deprecated",
+         "sphinxawesome.deprecated",
       ]
diff --git a/docs/how-to/add/includes/configure.inc b/docs/how-to/add/includes/configure.inc
@@ -1,3 +1 @@
 html_theme = "sphinxawesome_theme"
-# recommended:
-extensions += ["sphinxawesome_theme.highlighting"]
diff --git a/docs/how-to/build-your-own/includes/prepare-python-environment.rst b/docs/how-to/build-your-own/includes/prepare-python-environment.rst
@@ -11,7 +11,7 @@ The |product| uses these Python tools:
 
 .. _Poetry: https://python-poetry.org/
 .. _Nox: https://nox.thea.codes/en/stable/
-.. _Pipx: https://pypa.github.io/pipx/
+.. _Pipx: https://pipx.pypa.io/stable/
 
 If you want to use the same versions of the Python tools,
 you can provide a :gh:`requirements.txt <requirements.txt>` to the install commands.

diff --git a/docs/how-to/configure/includes/extensions.rst b/docs/how-to/configure/includes/extensions.rst
diff --git a/docs/how-to/configure/includes/syntax-highlighting.rst b/docs/how-to/configure/includes/syntax-highlighting.rst
@@ -0,0 +1,16 @@
+Syntax highlighting
+-------------------
+
+This theme lets you configure different color themes for syntax highlighting code blocks using these configuration options:
+
+.. code-block:: python
+   :caption: |conf|
+   :emphasize-text: PYGMENTS_THEME
+
+   # Select theme for both light and dark mode
+   pygments_style = "PYGMENTS_THEME"
+   # Select a different theme for dark mode
+   pygments_style_dark = "PYGMENTS_THEME"
+
+If you only set the :confval:`sphinx:pygments_style` option, the same style will be used in both light and dark modes.
+If you specify a ``pygments_style_dark`` option, different colors will be used in light and dark modes.
diff --git a/docs/how-to/configure/index.rst b/docs/how-to/configure/index.rst
@@ -9,7 +9,7 @@ Configure the theme
 
    Configure the |product|.
 
-.. include:: includes/extensions.rst
+.. include:: includes/syntax-highlighting.rst
 .. include:: includes/logos.rst
 .. include:: includes/sidebars.rst
 .. include:: includes/theme-options.rst

diff --git a/docs/how-to/customize/includes/color-scheme-different.rst b/docs/how-to/customize/includes/color-scheme-different.rst
diff --git a/docs/how-to/customize/includes/color-scheme-same.rst b/docs/how-to/customize/includes/color-scheme-same.rst
diff --git a/docs/how-to/customize/index.rst b/docs/how-to/customize/index.rst
@@ -15,7 +15,6 @@ Customize the theme
 .. toctree::
    :caption: In this section
 
-   syntax-highlighting
    css
    js
    templates
diff --git a/docs/how-to/customize/syntax-highlighting.rst b/docs/how-to/customize/syntax-highlighting.rst
diff --git a/docs/how-to/install/includes/fork-and-clone.rst b/docs/how-to/install/includes/fork-and-clone.rst
@@ -25,7 +25,7 @@ Create a local copy of the repository
 
         git clone https://github.com/kai687/sphinxawesome-theme.git
 
-.. _`fork the repository`: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+.. _`fork the repository`: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
 .. _`Clone the repository`: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
 
 After cloning the repository,

diff --git a/docs/index.rst b/docs/index.rst
@@ -44,7 +44,7 @@ Get started
 Upgrade
 -------
 
-If you want to upgrade to version |current| of the theme, see :ref:`sec:upgrade-to-5.0`.
+If you want to upgrade to version |current| of the theme, see :doc:`changelog/index`.
 
 Explore
 -------

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sphinxawesome-theme"
-version = "5.1.6"
+version = "5.2.0"
 description = "An awesome theme for the Sphinx documentation generator"
 readme = "README.md"
 authors = ["Kai Welke <kai687@pm.me>"]

diff --git a/src/theme-src/package.json b/src/theme-src/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sphinxawesome-theme",
-  "version": "5.1.6",
+  "version": "5.2.0",
   "scripts": {
     "build": "NODE_ENV=production webpack",
     "dev": "NODE_ENV=development webpack --watch --progress",

diff --git a/tests/test_basic.py b/tests/test_basic.py
@@ -10,7 +10,7 @@
 
 def test_returns_version() -> None:
     """It has the correct version."""
-    assert sphinxawesome_theme.__version__ == "5.1.6"
+    assert sphinxawesome_theme.__version__ == "5.2.0"
 
 
 @pytest.mark.sphinx("dummy")