### Install package using pip or uv with icons Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-iconify.rst This example shows how to use the ':iconify:' role to visually represent installation commands for pip and uv. It includes tabbed sections for different package managers. ```rst .. tab-set:: :class: outline .. tab-item:: :iconify:`devicon:pypi` pip .. code-block:: bash pip install shibuya .. tab-item:: :iconify:`material-icon-theme:uv` uv .. code-block:: bash uv add --dev shibuya ``` -------------------------------- ### Build Documentation with Sphinx Source: https://github.com/lepture/shibuya/blob/main/AGENTS.md Builds the project documentation using Sphinx. This command requires all dependencies to be installed first. The output will be generated in the `build/_html` directory. ```bash uv run sphinx-build docs build/_html ``` -------------------------------- ### Setup Node.js Dependencies for Static Assets Source: https://github.com/lepture/shibuya/blob/main/docs/contributing/index.rst Installs Node.js dependencies required for building static assets, typically for CSS preprocessors or JavaScript bundling. ```bash cd static npm install ``` -------------------------------- ### Install Dependencies with uv Source: https://github.com/lepture/shibuya/blob/main/AGENTS.md Installs all project dependencies using the uv package manager. This command ensures that the development environment is set up correctly for building the documentation and other project tasks. ```bash uv sync ``` -------------------------------- ### Sphinx Link Reference Examples Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Demonstrates various ways to create links and references in Sphinx documentation using reStructuredText. It includes examples for PEP references and general links. ```rst .. code-block:: rst :caption: links :class: demo-code In Sphinx, link is called reference. There are many ways to create a reference. For instance :pep:`8` is generated by ``:pep:`8```. In general, it is just a link_. .. _link: https://shibuya.lepture.com/ ``` -------------------------------- ### Install sphinxcontrib-mermaid using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/mermaid.rst This command installs the sphinxcontrib-mermaid package using pip, the Python package installer. Ensure you have pip installed and configured correctly. ```bash pip install sphinxcontrib-mermaid ``` -------------------------------- ### Install sphinx-docsearch Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/docsearch.rst Installs the sphinx-docsearch package using pip. This is the first step to integrate Algolia DocSearch with Sphinx. ```bash pip install sphinx-docsearch ``` -------------------------------- ### Autofunction Directive Source: https://github.com/lepture/shibuya/blob/main/docs/writing/api.rst Shows how to use the `autofunction` directive to document Python functions, with an example of controlling indexing. ```APIDOC ## Autofunction Directive Examples ### Description These examples illustrate the `autofunction` directive, which is used to automatically generate documentation for Python functions. The `:noindex:` option is shown to exclude the function from the index. ### Method N/A (Documentation Generation Directive) ### Endpoint N/A ### Parameters #### Path Parameters N/A #### Query Parameters N/A #### Request Body N/A ### Request Example ```rst .. autofunction:: babel.util.distinct :noindex: ``` ### Response #### Success Response (200) N/A (This is a documentation generation directive, not an API endpoint) #### Response Example N/A ``` -------------------------------- ### Complete Shibuya Configuration Example (Python) Source: https://context7.com/lepture/shibuya/llms.txt A comprehensive example of a `conf.py` file demonstrating the integration of various Shibuya features, including extensions for documentation generation, intersphinx, viewcode, copy button, design elements, and MyST parser. ```python # conf.py - Complete Shibuya configuration example import os project = "My Project" copyright = "2024, My Company" author = "My Team" version = "1.0.0" release = version extensions = [ "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", "sphinx_copybutton", "sphinx_design", "myst_parser", ] templates_path = ["_templates"] html_static_path = ["_static"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] ``` -------------------------------- ### Install sphinx-sqlalchemy using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-sqlalchemy.rst This snippet shows how to install the sphinx_sqlalchemy package using pip. It's a straightforward command-line operation. ```bash pip install sphinx_sqlalchemy ``` -------------------------------- ### Install sphinx-click using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-click.rst This command installs the sphinx-click package using pip. It's a prerequisite for using the plugin in your Sphinx project. ```bash pip install sphinx-click ``` -------------------------------- ### Install sphinx-togglebutton using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-togglebutton.rst This command installs the sphinx-togglebutton package using pip. It is a prerequisite for using the extension in your Sphinx project. ```bash pip install sphinx-togglebutton ``` -------------------------------- ### Install Shibuya Theme Source: https://github.com/lepture/shibuya/blob/main/README.md Installs the Shibuya Sphinx theme using pip. This is the first step to applying the theme to your Sphinx documentation. ```bash pip install shibuya ``` -------------------------------- ### Install sphinx-design Extension Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-design.rst Instructions for installing the sphinx-design extension using pip and adding it to the Sphinx configuration file (conf.py). ```bash pip install sphinx-design ``` ```python extensions = [ # ... "sphinx_design", ] ``` -------------------------------- ### Install sphinx-contributors using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-contributors.rst This command installs the sphinx-contributors package using pip. Ensure you have pip installed and accessible in your environment. ```bash pip install sphinx-contributors ``` -------------------------------- ### Install sphinx-tabs using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-tabs.rst This command installs the sphinx-tabs Python package using pip. It is a prerequisite for using the extension in Sphinx projects. ```bash pip install sphinx-tabs ``` -------------------------------- ### Sphinx Footnote Syntax Examples Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Illustrates four different methods for creating footnotes in Sphinx documentation: decimal numbers, auto-numbered, reference names, and auto-symbols. ```rst .. code-block:: rst a whole decimal number consisting of one or more digits, like [1]_ a single "#" will create auto-numbered footnotes [#]_ a "#" followed by a simple reference name [#note]_ a single "*" will create auto-symbol footnotes [*]_ .. [1] footnote for ``[1]`` .. [#] footnote for ``[#]`` .. [#note] footnote for ``[#note]`` .. [*] footnote for ``[*]`` ``` -------------------------------- ### Automodule Directive Source: https://github.com/lepture/shibuya/blob/main/docs/writing/api.rst Demonstrates the usage of the `automodule` directive to document Python modules. It shows options for including members and controlling indexing. ```APIDOC ## Automodule Directive Examples ### Description These examples show how to use the `automodule` directive to automatically generate documentation for Python modules. You can specify which members to include and whether to add them to the index. ### Method N/A (Documentation Generation Directive) ### Endpoint N/A ### Parameters #### Path Parameters N/A #### Query Parameters N/A #### Request Body N/A ### Request Example ```rst .. automodule:: babel.units :members: :noindex: ``` ### Response #### Success Response (200) N/A (This is a documentation generation directive, not an API endpoint) #### Response Example N/A ``` -------------------------------- ### Sphinx Citation Syntax Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Shows how to create citations in Sphinx documentation, which are similar to footnotes but use non-numeric labels. ```rst .. code-block:: rst Here is a citation reference: [CIT2002]_. .. [CIT2002] This is the citation. It's just like a footnote, except the label is textual. ``` -------------------------------- ### Run Shibuya Development Server Source: https://github.com/lepture/shibuya/blob/main/docs/contributing/index.rst Starts a local development server using 'serve.py'. This server typically includes live reloading for faster development cycles. ```bash python serve.py ``` -------------------------------- ### Install Shibuya Theme with uv Source: https://github.com/lepture/shibuya/blob/main/docs/install.rst Installs the Shibuya theme package using uv, a fast Python package installer and resolver. This command adds shibuya as a development dependency. ```bash uv add --dev shibuya ``` -------------------------------- ### Install Sphinx AutoAPI using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-autoapi.rst This command installs the sphinx-autoapi package using pip, the Python package installer. Ensure you have pip installed and accessible in your environment. ```bash pip install sphinx-autoapi ``` -------------------------------- ### Install sphinx-datatables using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-datatables.rst This command installs the sphinx-datatables package using pip. Ensure you have pip installed and accessible in your environment. ```bash pip install sphinx-datatables ``` -------------------------------- ### Install sphinx-copybutton using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-copybutton.rst This command installs the sphinx-copybutton package using pip, a Python package installer. Ensure you have pip installed and accessible in your environment. ```bash pip install sphinx-copybutton ``` -------------------------------- ### Start line numbering from a specific line with :lineno-start: Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/jupyter-sphinx.rst Demonstrates the ':lineno-start:' option with 'jupyter-execute'. This allows you to specify the starting line number for the numbering displayed alongside the source code. ```python .. jupyter-execute:: :lineno-start: 7 print('A') print('B') print('C') ``` -------------------------------- ### Install Sphinx Iconify Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-iconify.rst This snippet shows how to install the sphinx-iconify package using pip and how to add it to your Sphinx project's configuration file (conf.py). ```bash pip install sphinx-iconify ``` ```python extensions = [ # ... "sphinx_iconify", ] ``` -------------------------------- ### Sphinx 'tip' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Shows the 'tip' admonition, offering practical advice or useful shortcuts. ```rst .. tip:: Become a sponsor to keep this project sustainable. ``` -------------------------------- ### Sphinx 'hint' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Demonstrates the 'hint' admonition, providing helpful suggestions or tips to the reader. ```rst .. hint:: Authlib_ helps you build an OpenID Connect server. ``` -------------------------------- ### Install jupyter-sphinx using pip Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/jupyter-sphinx.rst This command installs the jupyter-sphinx package using pip. It's a prerequisite for using the jupyter-sphinx extension in your Sphinx documentation. ```bash pip install jupyter-sphinx ``` -------------------------------- ### Autoclass Directive Source: https://github.com/lepture/shibuya/blob/main/docs/writing/api.rst Illustrates the use of the `autoclass` directive for documenting Python classes, including options for member inclusion and indexing. ```APIDOC ## Autoclass Directive Examples ### Description These examples demonstrate the `autoclass` directive, used for generating documentation for Python classes. It allows for the inclusion of class members and control over indexing. ### Method N/A (Documentation Generation Directive) ### Endpoint N/A ### Parameters #### Path Parameters N/A #### Query Parameters N/A #### Request Body N/A ### Request Example ```rst .. autoclass:: babel.support.Format :members: :noindex: ``` ### Response #### Success Response (200) N/A (This is a documentation generation directive, not an API endpoint) #### Response Example N/A ``` -------------------------------- ### Sphinx Design Outline Tab Set (reStructuredText) Source: https://context7.com/lepture/shibuya/llms.txt Implement tabbed content using `sphinx-design` with an 'outline' class for distinct styling. This example shows installation commands for different package managers within the tabs. ```rst .. Outline tab-set (Shibuya-specific) .. tab-set:: :class: outline .. tab-item:: pip .. code-block:: bash pip install mypackage .. tab-item:: uv .. code-block:: bash uv add mypackage .. tab-item:: conda .. code-block:: bash conda install mypackage ``` -------------------------------- ### Install Python Development Dependencies Source: https://github.com/lepture/shibuya/blob/main/docs/contributing/index.rst Installs the necessary Python packages for development, including those listed in 'requirements-dev.lock' and 'livereload'. ```bash pip install -r requirements-dev.lock pip install livereload ``` -------------------------------- ### Install Numpydoc Extension Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/numpydoc.rst Installs the numpydoc Sphinx extension using pip. This is a prerequisite for enabling NumPy-style docstrings. ```bash pip install numpydoc ``` -------------------------------- ### Setup Python Virtual Environment with venv Source: https://github.com/lepture/shibuya/blob/main/docs/contributing/index.rst Creates and activates a Python virtual environment using the built-in 'venv' module. This isolates project dependencies. ```bash python -m venv .venv source .venv/bin/active ``` -------------------------------- ### Sphinx-Tabs Markup Syntax Examples Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-tabs.rst These reStructuredText (rst) examples demonstrate the various ways to create tabbed content using the sphinx-tabs extension, including basic tabs, group tabs, and code tabs for different programming languages. ```rst .. tabs:: .. tab:: Apples Apples are green, or sometimes red. .. tab:: Pears Pears are green. .. tab:: Oranges Oranges are orange. .. tabs:: .. group-tab:: Linux Linux Line 1 .. group-tab:: Mac OSX Mac OSX Line 1 .. group-tab:: Windows Windows Line 1 .. tabs:: .. group-tab:: Linux Linux Line 1 .. group-tab:: Mac OSX Mac OSX Line 1 .. group-tab:: Windows Windows Line 1 .. tabs:: .. code-tab:: c int main(const int argc, const char **argv) { return 0; } .. code-tab:: c++ int main(const int argc, const char **argv) { return 0; } .. code-tab:: py def main(): return ``` -------------------------------- ### Install MyST Parser for Sphinx (uv) Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/markdown.md Installs the 'myst-parser' package using the 'uv' package manager, suitable for development environments. This command adds the package as a development dependency. ```bash uv add --dev myst-parser ``` -------------------------------- ### Parsed Literal Example with Version Placeholder Source: https://github.com/lepture/shibuya/blob/main/docs/writing/code.rst Demonstrates the `parsed-literal` directive, which allows inline markup parsing within a literal block. This example shows a command with a version placeholder. ```text $ pip install shibuya==\ |version| ``` -------------------------------- ### reST Admonition Syntax Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Demonstrates the basic syntax for creating admonitions in reStructuredText. It shows a placeholder for an admonition name and its content. ```rst .. admonition-name:: content in admonition ``` -------------------------------- ### Generic Admonition with Custom Title Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Provides an example of using the generic 'admonition' directive with a custom title and content. ```rst .. admonition:: Typlog Typlog can help you hosting your blogs and podcasts. ``` -------------------------------- ### Install MyST Parser for Sphinx (pip) Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/markdown.md Installs the 'myst-parser' package, which enables Markdown support in Sphinx. This is a prerequisite for using MyST Markdown files in your documentation. ```bash pip install myst-parser ``` -------------------------------- ### Documenting Python Modules with Sphinx (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/api.rst This snippet shows how to use the `automodule` directive in reStructuredText (RST) to document Python modules. It includes options for displaying members and controlling indexing. This is useful for generating API references directly from Python code. ```rst .. automodule:: babel.units :members: :noindex: ``` ```rst .. automodule:: babel.units :members: ``` -------------------------------- ### Documenting Python Classes with Sphinx (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/api.rst This snippet demonstrates the use of the `autoclass` directive in reStructuredText (RST) for documenting Python classes. It allows for the inclusion of class members and control over indexing, facilitating the generation of detailed class API documentation. ```rst .. autoclass:: babel.support.Format :members: :noindex: ``` ```rst .. autoclass:: babel.support.Format :members: ``` -------------------------------- ### Sphinx 'seealso' Directive Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Shows the 'seealso' directive, which is used to suggest related information or resources. ```rst .. seealso:: The `blog post about Shibuya`_ by lepture. ``` -------------------------------- ### Install ipykernel to resolve kernel errors Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/jupyter-sphinx.rst This bash command installs the 'ipykernel' package. It's recommended if you encounter errors like 'Unable to find kernel (exception: No such kernel named python3)', as it provides the necessary Python kernel. ```bash pip install ipykernel ``` -------------------------------- ### Initialize New Translation File with pybabel Source: https://github.com/lepture/shibuya/blob/main/AGENTS.md Initializes a new translation file for a specific language. This command uses the extracted message template (`sphinx.pot`) to create a new `.po` file in the locale directory for the specified language. ```bash uv run pybabel init -D sphinx -i src/shibuya/locale/sphinx.pot -d src/shibuya/locale -l ``` -------------------------------- ### Sphinx 'warning' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Demonstrates the 'warning' admonition, used to alert readers to potential problems or actions to avoid. ```rst .. warning:: Do not ask your own questions in GitHub issues. ``` -------------------------------- ### Sphinx 'todo' Directive Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Demonstrates the 'todo' directive, used for marking tasks or items that need to be addressed later. Requires the 'sphinx.ext.todo' extension. ```rst .. todo:: Fix this UI issue later. ``` -------------------------------- ### Embed Video using sphinxcontrib-video (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/media.rst Provides an example of embedding a video using the .. video:: directive, which is typically provided by the sphinxcontrib-video extension. It shows basic alignment. ```rst .. video:: https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm :align: default ``` -------------------------------- ### Documenting Python Functions with Sphinx (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/api.rst This snippet illustrates the `autofunction` directive in reStructuredText (RST) for documenting Python functions. It enables the inclusion of function details and options to manage indexing, aiding in the creation of function-level API documentation. ```rst .. autofunction:: babel.util.distinct ``` ```rst .. autofunction:: babel.util.distinct :noindex: ``` -------------------------------- ### Sphinx 'caution' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Demonstrates the 'caution' admonition, used to warn readers about potential issues or risks. ```rst .. caution:: Livereload_ is using tornado for the server. ``` -------------------------------- ### Set Landing Page Layout using Meta Directive (reStructuredText) Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/layouts.rst This example shows how to apply the 'landing' layout to a specific page, typically the index page, using the `:layout:` meta directive in reStructuredText. This layout is often used for homepages. ```rst :layout: landing ``` -------------------------------- ### Compile Translations with pybabel Source: https://github.com/lepture/shibuya/blob/main/AGENTS.md Compiles the translated `.po` files into machine-readable message catalogs (`.mo` files). This step is necessary for Sphinx to load and use the translations. ```bash uv run pybabel compile -D sphinx -d src/shibuya/locale ``` -------------------------------- ### Sphinx Sidebar Configuration (Python) Source: https://context7.com/lepture/shibuya/llms.txt Configuration for HTML sidebars in Sphinx, specifying which sidebar templates to include. This example shows the default sidebars for all pages in the Shibuya theme. ```python html_sidebars = { "**": [ "sidebars/localtoc.html", "sidebars/repo-stats.html", "sidebars/edit-this-page.html", ] } ``` -------------------------------- ### Sphinx Numbered List Markup Source: https://github.com/lepture/shibuya/blob/main/docs/writing/lists.rst Illustrates the reStructuredText syntax for ordered (numbered, enumerated) lists. It covers various starting markers like numbers, upper-case letters, lower-case letters, and Roman numerals, followed by periods, right brackets, or parentheses. The example shows nested lists and how sequences are maintained. ```rst 1. numbers A. upper-case letters and it goes over many lines with two paragraphs and all! a. lower-case letters 3. with a sub-list starting at a different number 4. make sure the numbers are in the correct sequence though! I. upper-case roman numerals i. lower-case roman numerals (1) numbers again 1) and again ``` -------------------------------- ### Sphinx Keyboard Input Syntax Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Shows how to represent keyboard input using the ':kbd:' role in Sphinx, useful for documenting shortcuts and key presses. ```rst .. code-block:: rst :kbd:`Tab` means indent, :kbd:`Shift-Tab` means outdent. :kbd:`⌘+⇧+P` is power shortcuts in vscode. ``` -------------------------------- ### Initialize BuySellAds with Custom Template (JavaScript) Source: https://github.com/lepture/shibuya/blob/main/src/shibuya/theme/shibuya/extensions/buysellads.html This snippet initializes the BuySellAds script. It checks for the existence of the '_bsa' object and then calls its 'init' method. It supports a custom template for ad display and allows targeting either a default or a custom container based on availability. ```javascript (function() { if (typeof _bsa !== 'undefined' && _bsa) { let target = '#bsa-container'; if (document.querySelector('#bsa-custom-container')) { target = '#bsa-custom-container'; } _bsa.init('custom', '{{ buysellads_code }}', 'placement:{{ buysellads_placement }}', { target: target, template: `
##company## — ##tagline## ##description##
##callToAction##
Ads via BuySellAds ` }); } })(); ``` -------------------------------- ### Sphinx Subscript and Superscript Syntax Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Illustrates how to create subscript and superscript text in Sphinx documentation using the ':sub:' and ':sup:' roles. ```rst .. code-block:: rst :sub:`text in subscript` :sup:`text in superscript` ``` -------------------------------- ### Configure BuySellAds Context in Shibuya Theme (Python) Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/advertisement.rst This Python snippet shows how to configure BuySellAds within the `html_context` in `conf.py`. It requires 'buysellads_code', 'buysellads_placement', and 'buysellads_container_selector' for ad placement. ```python html_context = { "buysellads_code": "CE7DKK3M", "buysellads_placement": "shibuya", "buysellads_container_selector": ".yue > section > section", } ``` -------------------------------- ### Sphinx Menu Selection Syntax Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Illustrates the use of the ':menuselection:' role in Sphinx to represent menu paths in software interfaces. ```rst .. code-block:: rst :menuselection:`My --> Software --> Some menu --> Some sub menu 1 --> Some sub menu 2 --> Some sub menu 3` ``` -------------------------------- ### Sphinx 'important' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Illustrates the 'important' admonition, used to emphasize crucial information that readers should not miss. ```rst .. important:: I sometimes write blog posts on https://lepture.com ``` -------------------------------- ### Configure Multilingual Documentation in conf.py Source: https://context7.com/lepture/shibuya/llms.txt Enables support for multiple languages by defining a list of languages in `html_context`. Each language entry includes its display name, URL pattern, and locale code, allowing for a language switcher in the navigation. ```python # conf.py - Multilingual configuration html_context = { "languages": [ # (Display Name, URL Pattern, Locale Code) ("English", "/en/%s/", "en"), ("中文", "/zh/%s/", "zh"), ("日本語", "/ja/%s/", "ja"), ] } # Alternative: with country flags html_context = { "languages": [ ("🇺🇸 English", "/en/%s/", "en"), ("🇨🇳 中文", "/zh/%s/", "zh"), ] } # Alternative: direct links without dynamic URL pattern html_context = { "languages": [ ("English", "/en/"), ("中文", "/zh/"), ] } ``` -------------------------------- ### Sphinx Abbreviation Syntax Source: https://github.com/lepture/shibuya/blob/main/docs/writing/markup.rst Demonstrates the syntax for defining and using abbreviations in Sphinx documentation with the ':abbr:' role, including a tooltip on hover. ```rst .. code-block:: rst You can also include abbreviations like :abbr:`HTML (Hyper Text Markup Language)`. ``` -------------------------------- ### Sphinx 'versionadded' Directive Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Shows the 'versionadded' directive, used to indicate when a feature or change was introduced in a specific version. ```rst .. versionadded:: v3 Built-in reST renderer is added in Mistune. ``` -------------------------------- ### Sphinx 'error' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Shows the 'error' admonition, used to highlight errors or problems that have occurred or might occur. ```rst .. error:: One can not be divided by zero. ``` -------------------------------- ### Apply Container Classes to Images (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/media.rst Demonstrates how to use custom container classes (e.g., image-1, image-2) around an .. image:: directive. This allows for custom styling and layout of images. ```rst .. container:: image-1 .. image:: /_static/images/cat.jpg ``` ```rst .. container:: image-2 .. image:: /_static/images/cat.jpg ``` -------------------------------- ### Sphinx 'versionremoved' Directive Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Demonstrates the 'versionremoved' directive, used to indicate that a feature or functionality has been removed since a specific version. ```rst .. versionremoved:: 4.0 The :py:func:`spam` function is more flexible, and should be used instead. ``` -------------------------------- ### Sphinx 'versionchanged' Directive Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Illustrates the 'versionchanged' directive, used to highlight modifications made to a feature or functionality in a particular version. ```rst .. versionchanged:: v2 The ``jose`` module is moved out of Authlib. ``` -------------------------------- ### Jinja Template: Navigation and Branding Elements Source: https://github.com/lepture/shibuya/blob/main/src/shibuya/theme/shibuya/partials/site-head.html This Jinja template snippet demonstrates the usage of the `render_logo` macro to display light and dark themes for the logo, followed by the project name linked to the root documentation. It also includes various navigation and utility components. ```jinja [{{ render_logo(theme_light_logo, 'light-logo') }} {{ render_logo(theme_dark_logo, 'dark-logo') }} **{{ project }}**]({% if theme_logo_target %}{{ theme_logo_target }}{% else %}{{ pathto(root_doc) }}{% endif %}) ``` -------------------------------- ### Sphinx 'deprecated' Directive Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Shows the 'deprecated' directive, used to mark a feature or functionality as obsolete and scheduled for removal in future versions. ```rst .. deprecated:: 2.7 ``` -------------------------------- ### Sphinx 'note' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Illustrates the usage of the 'note' admonition directive in reStructuredText, commonly used for providing general information or tips. ```rst .. note:: ``note`` is a special directive for admonition. ``` -------------------------------- ### Advertisement Integration Configuration (Python) Source: https://context7.com/lepture/shibuya/llms.txt Integrate advertisement platforms like Carbon Ads, Ethical Ads, or BuySellAds into your documentation. Configuration varies depending on the ad provider and may involve `html_theme_options` or `html_context`. ```python # conf.py - Carbon Ads (displays in right sidebar) html_theme_options = { "carbon_ads_code": "your-carbon-code", "carbon_ads_placement": "your-carbon-placement", } # Ethical Ads (for Read the Docs hosting) html_theme_options = { "ethical_ads_publisher": "your-publisher-id", # Optional, defaults to readthedocs } # BuySellAds (requires template inclusion) html_context = { "buysellads_code": "your-code", "buysellads_placement": "your-placement", "buysellads_container_selector": ".yue > section > section", } ``` -------------------------------- ### Sphinx 'danger' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Illustrates the 'danger' admonition, intended for severe warnings about critical situations or actions that could lead to serious problems. ```rst .. danger:: A non-sustainable project is no trustworthy to use. ``` -------------------------------- ### Sphinx 'attention' Admonition Example Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Shows how to use the 'attention' admonition directive, typically for drawing the reader's attention to a critical piece of information. ```rst .. attention:: Shibuya is a well designed Sphinx theme. ``` -------------------------------- ### Enabling Sphinx 'todo' Extension Source: https://github.com/lepture/shibuya/blob/main/docs/writing/admonition.rst Illustrates how to enable the 'todo' extension in Sphinx by adding it to the 'extensions' list in 'conf.py' and setting 'todo_include_todos'. ```python extensions = [ "sphinx.ext.todo", ] todo_include_todos = True ``` -------------------------------- ### Displaying LaTeX with IPython Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/nbsphinx.ipynb Demonstrates how to display formatted text using LaTeX within an IPython environment. This allows for rich text formatting and mathematical typesetting. ```python from IPython.display import Latex Latex(r"This is a \LaTeX{} equation: $a^2 + b^2 = c^2$") ``` -------------------------------- ### Enable Template Path in conf.py Source: https://context7.com/lepture/shibuya/llms.txt Configures the path where custom HTML templates, such as partials for web fonts, are located. This is necessary for the documentation builder to find and include these custom templates. ```python # conf.py - Enable templates templates_path = ["_templates"] ``` -------------------------------- ### Generate New Language PO File (Bash) Source: https://github.com/lepture/shibuya/blob/main/docs/contributing/translations.rst Generates a new `.po` file for a specified language, which is necessary for starting translations. It requires a language code as an argument. ```bash make babel-init lang=it ``` -------------------------------- ### Align Image Left/Right with Options (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/media.rst Shows how to use the :align: option with the .. image:: directive to float an image to the left or right of the text. It also illustrates setting height and width. ```rst .. image:: /_static/icon-light.svg :align: left :height: 200 :width: 200 ``` ```rst .. image:: /_static/icon-light.svg :align: right :height: 200 :width: 200 ``` -------------------------------- ### Sphinx Nested List Markup Source: https://github.com/lepture/shibuya/blob/main/docs/writing/lists.rst Demonstrates the creation of complex nested lists in reStructuredText. This example combines unordered and ordered list items within each other to show hierarchical structuring. ```rst - A list - can contain another list 1. there are ordered list 2. and unordered list - The unordered list a. can have different style b. this ordered list is using ``a``, ``b``, etc c. instead of numbers ``` -------------------------------- ### Customize Document Text Color with CSS Variables Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/css.rst Example of using CSS variables to set the document text color for light and dark modes. The --yue-c-text variable is demonstrated. ```css html.light { --yue-c-text: #000; } html.dark { --yue-c-text: #fff; } ``` -------------------------------- ### Configure Simple Page Layout in Sphinx (Python) Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/layouts.rst This code snippet illustrates setting the 'simple' page layout globally in `conf.py`. The simple layout removes all sidebars, displaying only the main page content, which is ideal for single-page documentation. ```python html_theme_options = { "page_layout": "simple", } ``` -------------------------------- ### Customize Footer Background Color with CSS Variables Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/css.rst Example of using CSS variables to set the footer background color for both light and dark modes. The --sy-c-foot-background variable is used here. ```css html.light { --sy-c-foot-background: #f0f0f0; } html.dark { --sy-c-foot-background: black; } ``` -------------------------------- ### Create Simple Table with RST Fences Source: https://github.com/lepture/shibuya/blob/main/docs/writing/table.rst Demonstrates the basic syntax for creating simple tables using fences in reStructuredText. This method is suitable for straightforward tabular data. ```rst ===== ===== ====== A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== ``` ```rst ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== ``` -------------------------------- ### Sphinx Design Components: Tab Sets Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-design.rst Illustrates the creation of tabbed interfaces using 'tab-set' and 'tab-item' directives. Also shows 'tab-set-code' for code examples and combining tabs with code blocks. ```rst .. tab-set:: .. tab-item:: Label1 Content 1 .. tab-item:: Label2 Content 2 ``` ```rst .. tab-set-code:: .. code-block:: python foo = "str" .. code-block:: javascript a = 1; ``` ```rst .. tab-set:: .. tab-item:: Python .. code-block:: python :caption: a.py foo = "str" .. tab-item:: JavaScript .. code-block:: javascript :caption: b.js a = 1; ``` -------------------------------- ### Display Image using image directive (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/media.rst Demonstrates the basic usage of the .. image:: directive to embed an image within an RST document. This is a fundamental way to include graphical assets. ```rst .. image:: /_static/images/cat.jpg ``` -------------------------------- ### AI Integration and Copy Page Button Configuration (Python) Source: https://context7.com/lepture/shibuya/llms.txt Configure AI assistant integrations (ChatGPT, Claude, Perplexity) and the 'Copy page' button. This involves setting options in `html_theme_options` and `html_context` within the Sphinx configuration file. ```python # conf.py - AI integration configuration html_theme_options = { # Show/hide the copy page button "show_ai_links": True, # Enable specific AI assistant links "open_in_chatgpt": True, "open_in_claude": True, "open_in_perplexity": True, # Custom prompt template ({url} is replaced with page URL) "ai_prompt_template": "Read {url} and help me understand it.", } # Required for copy page to work with GitHub source html_context = { "source_type": "github", "source_user": "username", "source_repo": "project", } # Alternative: use Sphinx's copy source feature html_baseurl = "https://docs.example.com/" html_copy_source = True ``` -------------------------------- ### Add Custom Social Icons to Navbar Source: https://github.com/lepture/shibuya/blob/main/docs/customisation/icons.rst Provides an example of how to customize the navbar to include additional social network links. This involves overriding the 'nav-socials.html' partial and adding an anchor tag with an Iconify icon. ```html
{%- include "components/nav-socials.html" -%}
``` -------------------------------- ### Extract Translation Messages with pybabel Source: https://github.com/lepture/shibuya/blob/main/AGENTS.md Extracts translatable messages from the Shibuya theme files using pybabel. This command generates a template file (`sphinx.pot`) that contains all strings needing translation. ```bash uv run pybabel extract -F babel.cfg src/shibuya/theme -o src/shibuya/locale/sphinx.pot ``` -------------------------------- ### Configure sphinx-sqlalchemy in conf.py Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-sqlalchemy.rst This snippet demonstrates how to add 'sphinx_sqlalchemy' to the extensions list in your Sphinx project's conf.py file. This enables the extension's directives. ```python extensions = [ 'sphinx_sqlalchemy', ] ``` -------------------------------- ### Sphinx Option List Markup Source: https://github.com/lepture/shibuya/blob/main/docs/writing/lists.rst Demonstrates the reStructuredText syntax for option lists, used to describe command-line options. It covers single-letter options, long options, options with arguments, and options with multiple paragraphs in their descriptions. ```rst -a Output all. -b Output both (this description is quite long). -c arg Output just arg. --long Output all day long. -p This option has two paragraphs in the description. This is the first. This is the second. Blank lines may be omitted between options (as above) or left in (as here and below). --very-long-option A VMS-style option. Note the adjustment for the required two spaces. --an-even-longer-option The description can also start on the next line. -2, --two This option has two variants. -f FILE, --file=FILE These two options are synonyms; both have arguments. /V A VMS/DOS-style option. ``` -------------------------------- ### Sphinx Field List Markup Source: https://github.com/lepture/shibuya/blob/main/docs/writing/lists.rst Illustrates the reStructuredText syntax for field lists, commonly used for metadata like dates, versions, or authors. Fields start with a colon, followed by the field name and its value. ```rst :Date: 2001-08-16 :Version: 1 :Authors: - Me - Myself - I ``` -------------------------------- ### Sphinx Design Grid Cards with Surface Styling (reStructuredText) Source: https://context7.com/lepture/shibuya/llms.txt Create grid layouts with cards using the `sphinx-design` extension. This example demonstrates Shibuya-specific 'surface' styling for the grid container and includes icons and links within the cards. ```rst .. Grid cards with surface styling (Shibuya-specific) .. grid:: 1 1 2 3 :gutter: 2 :padding: 0 :class-container: surface .. grid-item-card:: :octicon:`star` Feature One :link: /features/one/ Description of feature one with modern styling. .. grid-item-card:: :octicon:`zap` Feature Two :link: /features/two/ Description of feature two. .. grid-item-card:: :octicon:`moon` Feature Three Description of feature three. ``` -------------------------------- ### Sphinx HTML Context Configuration (Python) Source: https://context7.com/lepture/shibuya/llms.txt Configuration for HTML context variables in Sphinx, used to provide source repository information. This is often utilized by themes to display links to the source code or documentation path. ```python html_context = { "source_type": "github", "source_user": "mycompany", "source_repo": "myproject", "source_version": "main", "source_docs_path": "/docs/", } ``` -------------------------------- ### Apply 'toggle' class to images in reStructuredText Source: https://github.com/lepture/shibuya/blob/main/docs/extensions/sphinx-togglebutton.rst This reStructuredText syntax applies the 'toggle' class to an image. While the provided example shows a GIF, this class is intended for elements that can be toggled, though its specific behavior with images might depend on custom CSS. ```rst .. image:: https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif :class: toggle ``` -------------------------------- ### Algolia DocSearch Integration Configuration (Python) Source: https://context7.com/lepture/shibuya/llms.txt Replace Sphinx's default search with Algolia DocSearch for enhanced search functionality. This requires adding the `sphinx_docsearch` extension and configuring your Algolia application ID, API key, and index name. ```python # conf.py - DocSearch configuration extensions = [ "sphinx_docsearch", ] docsearch_app_id = "YOUR_APP_ID" docsearch_api_key = "YOUR_SEARCH_API_KEY" docsearch_index_name = "YOUR_INDEX_NAME" # Fix conflicts with Jupyter extensions nbsphinx_requirejs_path = "" jupyter_sphinx_require_url = "" ``` -------------------------------- ### Expand URL Macro - Jinja2 Source: https://github.com/lepture/shibuya/blob/main/src/shibuya/theme/shibuya/components/nav-links.html The `expandURL` macro handles the expansion of URLs. It checks if a URL starts with 'https://' or 'http://'. If it does, the URL is returned as is. Otherwise, it uses the `pathto` function to resolve the URL, optionally considering it as a resource. ```jinja2 {% macro expandURL(url, resource=False) %} {% if url.startswith(('https://', 'http://')) %} {{ url }} {% else %} {{ pathto(url, resource=resource) }} {% endif %} {% endmacro %} ``` -------------------------------- ### Embed Video using 'video' directive (RST) Source: https://github.com/lepture/shibuya/blob/main/docs/writing/media.rst This snippet shows how to embed a video using the 'video' directive, likely from a different extension or a custom implementation. It takes a direct URL to the video file. This is an alternative to embedding YouTube videos. ```rst .. video:: https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm ```