mystx.ext.github_readme_stats
=============================

.. py:module:: mystx.ext.github_readme_stats

.. autoapi-nested-parse::

   mystx.ext.github_stats — GitHub Readme Stats 指令入口

   该子包提供三条指令，用于在 Sphinx 文档中嵌入 GitHub Readme Stats 卡片:

   - ``github-stats``：用户统计卡片；
   - ``github-top-langs``：常用语言占比卡片；
   - ``github-pinned-repo``：置顶仓库卡片。

   此模块导出指令类，并提供 ``setup(app)`` 以便 Sphinx 自动注册。

   注意：卡片由外部服务 ``https://github-readme-stats.vercel.app/`` 渲染，选项与主题取值以该服务为准。



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/mystx/ext/github_readme_stats/base/index
   /autoapi/mystx/ext/github_readme_stats/pinned_repo/index
   /autoapi/mystx/ext/github_readme_stats/stats/index
   /autoapi/mystx/ext/github_readme_stats/top_langs/index
   /autoapi/mystx/ext/github_readme_stats/wakatime/index


Classes
-------

.. autoapisummary::

   mystx.ext.github_readme_stats.GitHubStatsDirective
   mystx.ext.github_readme_stats.GitHubTopLangsDirective
   mystx.ext.github_readme_stats.GitHubPinnedRepoDirective
   mystx.ext.github_readme_stats.GitHubWakaTimeDirective


Functions
---------

.. autoapisummary::

   mystx.ext.github_readme_stats.setup


Package Contents
----------------

.. py:class:: GitHubStatsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

   Bases: :py:obj:`mystx.ext.github_readme_stats.base.BaseGitHubCardDirective`


   渲染 GitHub 用户基础统计卡片。

   选项:

   - ``username`` （必填）：GitHub 用户名；
   - ``theme`` （ 可选）：主题名称，默认为 default；
   - ``show_icons`` （可选 flag）：出现该选项即开启图标显示；
   - ``hide`` （可选）：以逗号分隔的统计项列表，例如 issues,contribs。

   Example:

       .. code-block:: rst

           .. github-stats::
               :username: octocat
               :theme: dark
               :show_icons:
               :hide: issues,contribs


   .. py:attribute:: option_spec

      Mapping of option names to validator functions.



   .. py:method:: run()

      根据选项构建统计卡片 URL 并返回 HTML 节点。

      Returns:
          list[nodes.Node]: 单元素列表，包含原始 HTML ``<img>`` 节点。



.. py:class:: GitHubTopLangsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

   Bases: :py:obj:`mystx.ext.github_readme_stats.base.BaseGitHubCardDirective`


   渲染 GitHub Top Languages 卡片。

   选项:

   - ``username`` （必填）：GitHub 用户名；
   - ``layout`` （可选）：布局样式，默认为 ``compact``；
   - ``theme`` （可选）：主题名称，默认为 ``default``；
   - ``langs_count`` （可选）：展示语言数量，默认为 ``6``。

   Example:

       .. code-block:: rst

           .. github-top-langs::
               :username: octocat
               :layout: compact
               :theme: dark
               :langs_count: 8


   .. py:attribute:: option_spec

      Mapping of option names to validator functions.



   .. py:method:: run()

      根据选项构建 Top Languages 卡片 URL 并返回 HTML 节点。

      Returns:
          list[nodes.Node]: 单元素列表，包含原始 HTML ``<img>`` 节点。



.. py:class:: GitHubPinnedRepoDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

   Bases: :py:obj:`mystx.ext.github_readme_stats.base.BaseGitHubCardDirective`


   渲染 GitHub 置顶仓库卡片。

   选项:

   - username（必填）：GitHub 用户名；
   - repo（必填）：仓库名；
   - theme（可选）：主题名称，默认为 default。
   - link（可选）：点击卡片跳转的链接地址。

   示例参见模块文档的用法。


   .. py:attribute:: option_spec

      Mapping of option names to validator functions.



   .. py:method:: run()

      根据指令选项构建卡片 URL 并返回 HTML 节点。

      Returns:
          list[nodes.Node]: 单元素列表，包含原始 HTML ``<img>`` 节点。



.. py:class:: GitHubWakaTimeDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

   Bases: :py:obj:`mystx.ext.github_readme_stats.base.BaseGitHubCardDirective`


   渲染 WakaTime 统计卡片。

   选项见模块文档说明。


   .. py:attribute:: option_spec

      Mapping of option names to validator functions.



   .. py:method:: run()

      根据选项构建 WakaTime 卡片 URL 并返回 HTML 节点。



.. py:function:: setup(app)

   注册三条 GitHub Stats 相关指令到 Sphinx。

   Args:
       app: Sphinx 应用实例。

   Returns:
       dict: 扩展元信息，包含版本号与并行读取安全性标识。