斯芬克斯的ETH宇宙学主题,2013版。
sphinx-pynpoint-theme的Python项目详细描述
查看readthedocs.org上的工作demo。
这是我为readthedocs.org制作的移动友好sphinx主题原型。是的 目前正在开发中,包括一些可以忽略的RTD变量检查 如果你只是想在网站之外的项目中使用它。
安装
VIA套餐
下载包或将其添加到requirements.txt文件:
$ pip install sphinx_rtd_theme
在conf.py文件中:
importsphinx_rtd_themehtml_theme="sphinx_rtd_theme"html_theme_path=[sphinx_rtd_theme.get_html_theme_path()]
通过git或下载
将sphinx_rtd_theme/sphinx_rtd_theme存储库符号链接或子树到 docs/_themes/sphinx_rtd_theme然后将以下两个设置添加到sphinx conf.py文件:
html_theme="sphinx_rtd_theme"html_theme_path=["_themes",]
如何建立目录
当前,左菜单将基于index.rst文件中定义的任何toctree(s)生成。 它输出两个深度级别,这将使您的访问者能够更高级别地访问您的 文件。如果没有设置toctree,则主题将恢复为sphinx通常的本地toctree。
重要的是要注意,如果你不遵循相同的样式为你的第一个标题 您的文档,目录树将被错误构建,结果菜单可能不会显示正确的 渲染时的深度。
贡献或修改主题
sphinx_rtd_主题主要是一个sass项目,需要一些其他sass库。我是 使用bower来管理这些依赖项,并使用compass来构建css。好消息是 我有一组非常好的grunt操作,它们不仅可以加载这些依赖项,还可以监视 对于更改,重建sphinx演示文档并构建主题的可分发版本。 坏消息是,这意味着您需要设置类似的环境 前端开发人员(与python开发人员相比)。这意味着要安装node和ruby。
设置您的环境
- 将sphinx安装到虚拟环境中。
pip install sphinx
- 安装SASS和指南针
gem install sass compass
- 安装node、bower和grunt。
// Install node brew install node // Install bower and grunt npm install -g bower grunt-cli // Now that everything is installed, let's install the theme dependecies. npm install
现在我们的环境已经设置好,请确保您处于虚拟环境中,转到 这个存储库在您的终端中并运行grunt:
grunt
此默认任务将执行以下非常酷的操作,值得您费心。
- 它将安装和更新任何bower依赖项。
- 它将运行sphinx并构建新的文档。
- 它将监视sass文件的更改,并根据更改构建css。
- 只要注意到.rst、.html、.js的更改,它就会重新生成sphinx文档。 或.css文件。
在发送拉取请求之前
完成编辑后,可以运行grunt build来清除旧的 文件和重建新的发行版,压缩css并清除 无关文件。请在发送PR之前执行此操作。
待办事项
- 用大量的rst示例构建真正的演示文档
- 更新到FontAwesome4.0并从Bower构建它,而不是我现在的复制/粘贴黑客。
- 在主题级别分离一些sass变量,以便覆盖一些基本颜色。
- 添加设置徽标的功能。