Set up your development workflow#

The following instructions will help you set up a basic development environment so that you can begin experimenting with changes. This covers the basics, and see the other sections of the Contributing Guide for more details.

设置开发环境#

First we’ll install the necessary tools that you can use to begin making changes. Follow these steps:

  1. 使用 git 获取这个项目的源代码：

    git clone https://github.com/executablebooks/sphinx-book-theme
cd sphinx-book-theme

  2. Ensure you have Python 3.7 or newer!

  3. Install tox. tox is a tool for managing virtual environments for test suites or common jobs that are run with a repository. It ensures that your environment is consistent each time you build the docs or run tests.

    $ pip install tox

  4. Install pre-commit. We use pre-commit to ensure that the code meets certain standards any time a commit is made.

    $ pip install pre-commit

    Next, follow the pre-commit installation instructions.

    Finally, install the local dependencies for pre-commit. Run the following command in the same folder as the repository:

    $ pre-commit install

The rest of these instructions use tox to automate the installation and commands necessary to do many common things.

Build the documentation#

Now that you’ve installed the necessary tools, try building the documentation for this theme locally. To do so, run the following tox command:

$ tox -e docs-update

This will build the documentation using the latest version of the theme and put the outputs in docs/_build/html. You may then preview them by opening one of the HTML files.

Update the theme’s assets (CSS/JS)#

Now that you’ve previewed the documentation, try making changes to this theme’s assets and see how they affect the documentation builds. This is an easy way to preview the effect that your changes will make.

First, make your changes in src/sphinx_book_theme/assets/. This folder contains all of the SCSS and Javascript that are used in this site. For example, edit one of the scss files to add or modify a rule.

Next, compile the changes. Run the following command:

$ tox -e compile

This uses the Sphinx Theme Builder to compile our SCSS/JS files and bundle them with our theme at src/sphinx_book_theme/theme/sphinx_book_theme/static. These compiled assets are not included in our git repository, but they are included in distributions of the theme.

Finally, re-build the documentation to preview your changes:

$ rm -rf docs/_build/html
$ tox -e docs-update

When you open the HTML files for the documentation, your changes should be reflected.

当你进行修改时，自动构建文档#

You can bundle both of the steps above into a single command, which also opens a live server that watches for changes to the theme’s assets and documentation, and automatically compiles changes + re-builds the theme.

To do so, use this tox command:

$ tox -e docs-live

这将做到以下几点：

  • 生成主题的文档（类似于运行 tox -e docs-update）

  • Start a development server on an available port 127.0.0.1:xxxx

  • 在你的默认浏览器中打开它

  • 观察变化并自动重新生成文档，在发生变化时自动重新加载浏览器。

有了这个，你可以在编辑器中修改主题，并看到这些修改在浏览器上是如何呈现的。

Run the tests#

Once you’ve made a change to the theme, you should confirm that the tests still pass, and potentially add or modify a test for your changes.

To run the test suite with the default tox environment, simply run this command:

$ tox

This will run pytest against all of the files in tests/ and display the result. You can pass arguments to the pytest command like so:

$ tox -- -k test_match

Anything passed after -- will be passed directly to pytest.

参见

See Testing infrastructure for more information.

The {example} directive#

This theme uses the sphinx-examples extension to make it easy to quickly show off example snippets.

Basic usage is like so:

```{example} Example title
This will be both **rendered** and **shown as source code**.
```

Example title

This will be both **rendered** and **shown as source code**.

This will be both rendered and shown as source code.

See the sphinx-examples documentation for more details.