Sphinx Charts

使用plotly v2.8.3和D3为sphinx创建交互式图表、图形和图像。

文档在这里.

快速入门

请参阅上面的文档获取更多信息，但简而言之，将扩展添加到您的 conf.py 文件中

extensions = [
    ...
    'sphinx_charts.charts'
]

将以下内容粘贴到新文件 <your_docs_src_directory>/charts/test.json 中

{
  "data": [
    {
      "x": [1, 2, 3, 4, 5],
      "y": [1, 2, 4, 8, 16]
    }
  ],
  "layout": {
    "margin": {"t": 15, "b": 30, "r": 15, "l": 35}
  }
}

在您的 *.rst 文件中包含以下指令

.. chart:: charts/test.json

    This is the caption of the chart

... 然后出发！

开发者说明

注意：除非您计划开发sphinx_charts本身，否则请忽略以下内容。

入门

1. 点击右上角的“使用此模板”，然后出发。
2. 在您的新仓库中搜索 {{ 。对各种术语进行搜索和替换 - 很明显，例如将 {{github_username}} 替换为您的github用户名！
3. 在LICENSE中设置您所需的许可证。
4. 如果您需要部署到pypi，您必须手动进行首次部署 - travis无法为您完成此操作。查看打包说明。

Pre-Commit

您需要安装pre-commit以使钩子工作。执行以下操作：

pip install pre-commit
pre-commit install

完成之后，每次提交代码时，都会进行以下检查

• 有效的github仓库和文件
• 代码风格
• 导入顺序
• PEP8合规性
• 文档构建

如果失败，提交将停止。 重新运行提交将自动修复大多数问题 除了

• flake8检查...希望随着时间的推移，Black（它已经自动修复了大多数问题）将消除对它的需求。
• 在成功提交之前，您必须自己修复文档（对此没有自动修复功能!!）。

您还可以在不提交的情况下运行pre-commit钩子，例如

pre-commit run black --all-files

或

# -v gives verbose output, useful for figuring out why docs won't build
pre-commit run build-docs -v

贡献

• 请在板上提出问题（或添加您的意见）以便维护者了解情况并提供建议/指导。

• 为{{library_name}}创建一个分叉，在一个新的分支上进行您的更改（请参阅.pre-commit-config.yaml以了解分支命名约定）。要运行测试和提交，您需要进行如下操作

git clone <your_forked_repo_address>    # fetches the repo to your local machine
cd sphinx_charts                     # move into the repo directory
pyenv virtualenv 3.6.9 myenv            # Makes a virtual environment for you to install the dev tools into. Use any python >= 3.6
pyend activate myenv                    # Activates the virtual environment so you don't screw up other installations
pip install -r requirements-dev.txt     # Installs the testing and code formatting utilities
pre-commit install                      # Installs the pre-commit code formatting hooks in the git repo
tox                                     # Runs the tests with coverage. NB you can also just set up pycharm or vscode to run these.

• 采用测试驱动开发的方法来实现新功能或修复错误。

• 向sphinx_charts维护者询问在哪里提交您的pull请求。我们将根据路线图创建一个版本分支，您可以在此分支上提交您的PR。我们将帮助审查更改并改进PR。

• 一旦检查通过，新代码的测试覆盖率>=95%，文档已更新且审查通过，我们将将其合并到版本分支中。

• 一旦完成该版本的所有路线图功能，我们将发布。

发布流程

创建新版本的流程如下

1. 检出下一个版本的分叉，名为vX.Y.Z
2. 向master分支创建一个Pull Request。
3. 执行您的更改，提交并推送到分支vX.Y.Z
4. 确保文档已更新以匹配更改，并更新更改日志。不更新文档的Pull Request将被拒绝。
5. 确保测试覆盖率足够。减少测试覆盖率的Pull Request将被拒绝。
6. 确保代码符合样式指南（否则pre-commit脚本和flake8测试将失败）
7. 处理PR上的审查意见
8. 确保setup.py中的版本号正确且与分支版本匹配。
9. 合并到master。成功的测试、文档构建、flake8和新的版本号将自动在pypi上创建发布。
10. 转到代码>发布，在相同的SHA上GitHub创建一个新的发布。

文档

自动构建文档

当您提交时，将在预配置的环境中自动构建文档。

实际上，pre-commit的工作方式是，除非文档构建成功，否则不允许您提交代码，这样我们可以避免在任一提交sha上推送损坏的文档，因此我们可以依赖构建成功。

手动构建文档

如果您需要构建文档

安装doxgen。在mac上，这是brew install doxygen；其他系统可能不同。

安装sphinx和其他构建文档所需的要求

pip install -r docs/requirements.txt

运行构建过程

sphinx-build -b html docs/source docs/build