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


Classes
-------

.. autoapisummary::

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


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`。

   示例（reStructuredText）：

   .. 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`。

   示例（reStructuredText）：

   .. 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`。

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


   .. py:attribute:: option_spec

      Mapping of option names to validator functions.



   .. py:method:: run()

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

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



.. py:function:: setup(app)

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

   Args:
       app: Sphinx 应用实例。

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