From 52e4ca77785dee71436b06676c2827fe6dc83492 Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Thu, 30 May 2024 23:19:35 +0200 Subject: [PATCH] docs: update --- README.md | 12 ++------- docs/about.rst | 6 ++--- docs/changelog/includes/5.0.rst | 3 +-- docs/changelog/includes/5.2.rst | 5 ++++ docs/changelog/index.rst | 1 + docs/conf.py | 3 --- docs/how-to/add/includes/add-to-sphinx.rst | 6 ++--- docs/how-to/add/includes/configure.inc | 2 -- .../includes/prepare-python-environment.rst | 2 +- docs/how-to/configure/includes/extensions.rst | 23 ----------------- .../includes/syntax-highlighting.rst | 16 ++++++++++++ docs/how-to/configure/index.rst | 2 +- .../includes/color-scheme-different.rst | 25 ------------------- .../customize/includes/color-scheme-same.rst | 20 --------------- docs/how-to/customize/index.rst | 1 - docs/how-to/customize/syntax-highlighting.rst | 20 --------------- .../install/includes/fork-and-clone.rst | 2 +- docs/index.rst | 2 +- pyproject.toml | 2 +- src/theme-src/package.json | 2 +- tests/test_basic.py | 2 +- 21 files changed, 37 insertions(+), 120 deletions(-) create mode 100644 docs/changelog/includes/5.2.rst delete mode 100644 docs/how-to/configure/includes/extensions.rst create mode 100644 docs/how-to/configure/includes/syntax-highlighting.rst delete mode 100644 docs/how-to/customize/includes/color-scheme-different.rst delete mode 100644 docs/how-to/customize/includes/color-scheme-same.rst delete mode 100644 docs/how-to/customize/syntax-highlighting.rst diff --git a/README.md b/README.md index b4374d8a7..8ec01f067 100644 --- a/README.md +++ b/README.md @@ -30,13 +30,6 @@ 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. @@ -44,8 +37,7 @@ With the Awesome Theme, you can build readable, functional, and beautiful docume ### 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 index 28da432e7..3e194c0b7 100644 --- 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 `__ | +| UI design | `shadcn/ui`_ | `MIT License `__ | +---------------------------------------------------------+-------------------------------+-----------------------------------------------------------------------------------+ | CSS framework | Tailwind_ | `MIT 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 index 66d572c7b..47071f8eb 100644 --- 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 `_. @@ -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 `_. +**DocSearch** is now an external extension, available as `sphinx-docsearch `_. ``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 new file mode 100644 index 000000000..b3cca94f3 --- /dev/null +++ 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 index 6d7eb143d..bd5970464 100644 --- 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 index b7b03688a..900922b38 100644 --- 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 index 6e55d4169..e147fca63 100644 --- 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 index f868dd7f8..a71b8567c 100644 --- 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 index 2cf3e942d..f1032faf8 100644 --- 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 ` to the install commands. diff --git a/docs/how-to/configure/includes/extensions.rst b/docs/how-to/configure/includes/extensions.rst deleted file mode 100644 index d9a6005ef..000000000 --- a/docs/how-to/configure/includes/extensions.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _sec:bundled-extensions: - -Bundled extensions ------------------- - -The |product| bundles one Sphinx extension for better code blocks. - -``sphinxawesome_theme.highlighting`` - Adds the following highlighting options to Sphinx's ``code-block`` directive: - - - :samp:`:emphasize-added: {LINES}`: highlight lines to be added. - - :samp:`:emphasize-removed: {LINES}`: highlight lines to be removed. - - :samp:`:emphasize-text: {TEXT}`: highlight a placeholder word or phrase. - - .. note:: - - If you don't add this extension, the spacing in code blocks might appear off. - You can :ref:`sec:custom-css` with extra padding to ``pre`` elements. - -.. seealso:: - - :doc:`/demo/code-blocks`, - :confval:`sphinx:extensions` diff --git a/docs/how-to/configure/includes/syntax-highlighting.rst b/docs/how-to/configure/includes/syntax-highlighting.rst new file mode 100644 index 000000000..b9327e82a --- /dev/null +++ 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 index edcfb407c..f6010ec23 100644 --- 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 deleted file mode 100644 index 69e60b24c..000000000 --- a/docs/how-to/customize/includes/color-scheme-different.rst +++ /dev/null @@ -1,25 +0,0 @@ -Select different color schemes for light and dark modes -------------------------------------------------------- - -If you want to use different color schemes for syntax highlighting in light and dark mode, -follow these steps: - -#. Select a theme you want to use in light mode and :ref:`set it as your color scheme ` with the ``pygments_style`` option. -#. Select a color scheme you want to use in dark mode and run the following command: - - .. code-block:: sh - :emphasize-text: THEME - - pygmentize -s THEME -f html -a .dark > pygments-dark.css - - This runs the ``pygmentize`` command, which is part of the Pygments package. - If you installed the |product|, Pygments is also installed. - -#. Add the file :file:`pygments-dark.css` as :ref:`custom css `. - -.. dropdown:: More information - - Themes can define ``pygments_style`` and ``pygments_style_dark`` options in their :file:`themes.conf` file. - This applies different color schemes in light and dark mode based on the system settings and the ``prefers-color-scheme`` media query. - However, this doesn't work with manual theme switchers that select different CSS based on classes. - Therefore, we have to add the styles for dark mode as custom CSS. diff --git a/docs/how-to/customize/includes/color-scheme-same.rst b/docs/how-to/customize/includes/color-scheme-same.rst deleted file mode 100644 index bdc0fd59c..000000000 --- a/docs/how-to/customize/includes/color-scheme-same.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _sec:set-color-scheme: - -Select color schemes for syntax highlighting --------------------------------------------- - -Syntax highlighting is provided by the Pygments library and the *bw* color scheme. -To select a different color scheme **for both light and dark mode**, -use the :confval:`sphinx:pygments_style` option: - -.. code-block:: python - :caption: |conf| - :emphasize-text: PYGMENTS_THEME - - pygments_style = "PYGMENTS_THEME" - -For a list of available themes, see the Pygments_ documentation. -For even more themes, see the `accessible pygments themes`_ project. - -.. _Pygments: https://pygments.org/styles/ -.. _accessible pygments themes: https://github.com/Quansight-Labs/accessible-pygments diff --git a/docs/how-to/customize/index.rst b/docs/how-to/customize/index.rst index 6413641c2..589b282d1 100644 --- 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 deleted file mode 100644 index 468568300..000000000 --- a/docs/how-to/customize/syntax-highlighting.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. meta:: - :description: Select syntax highlighting color schemes. - :twitter:description: Select syntax highlighting color schemes. - -Syntax highlighting -=================== - -.. rst-class:: lead - - Select different color schemes for syntax highlighting in code blocks. - -.. tip:: - - When selecting different color schemes, - make sure that it works in all situations with sufficient contrast, - for example, with line highlighting or with captions. - Check the background colors and code block borders for overlaps. - -.. include:: includes/color-scheme-same.rst -.. include:: includes/color-scheme-different.rst diff --git a/docs/how-to/install/includes/fork-and-clone.rst b/docs/how-to/install/includes/fork-and-clone.rst index ad9f36236..cb2e12ebf 100644 --- 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 index 8e6e13419..1bed3015e 100644 --- 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 index de12d80b3..2e0471253 100644 --- 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 "] diff --git a/src/theme-src/package.json b/src/theme-src/package.json index dc9acb6e7..18fb4fa69 100644 --- 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 index 91bcf12c5..9194dbdef 100644 --- 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")