/docs.taichi.graphics

Home of the Taichi documentation site.

Primary LanguageHTML

Taichi Documentation Site

Netlify Status Crowdin

English | 中文

A static documentation website built with docusaurus for Taichi documentation.

💡 Please make sure you understand the following before moving forward:

  • If you want to update any Taichi documentation, go to the main repository instead and please do not work on this repo! This repo only hosts the mirrored version of the docs in order to build and deploy the documentation website.
  • If you want to contribute to the translations of any Taichi documentation, go to Our Translation Page instead. Our help-us-translate page has more details about the i18n workflow. Note: we don't support deploy-previews for translations for performance reasons, and usually you don't need to preview the full website for translation strings.
  • If you want to update any non-doc pages that are not versioned (e.g., the community and help-us-translate pages), you are at the right place. We welcome pull requests directly to this repo!
  • If you want to make a functional change to the website, such as updating the styles or adding a new React component, you are at the right place. We welcome related pull requests directly to this repo!
Tips for Documentation Website Maintainers

We follow the corresponding docusaurus guide for the translation setup. Please refer to the guide for technical details.

If you want to spin up the development server locally for a specific locale, add --locale TARGET_LOCALE after the command. For example, in order to start the server for zh-Hans:

yarn --cwd=website start --locale zh-Hans

To preview the translated website, you can use

yarn --cwd=website run crowdin download

to download approved translations to your local disk, and run the start command listed above to preview the website in your desired locale locally. Note you may need to set the corresponding environment variable CROWDIN_TOKEN locally. It can be generated from the Crowdin settings page, if you have the right permission.

You need to periodically check/refactor the file structure on Crowdin for any source file refactor. Please see more details here.

Prerequisites

You need to install the following before setting up this project:

  • yarn
  1. On macOS, you can install the above by:
brew install yarn
  1. On Debian-based Linux distribution, you can install the above by:
sudo apt install yarn

For Arch Linux, use the following command:

sudo pacman -S yarn
  1. To install yarn on Windows, you need to install Node.js first. You can check it using node -v‘ in the terminal. After it's verified, download the Yarn installer(.smi) from the official yarn website and install it. To verifiy the installation, use yarn --version.

Setup

Install all of the dependencies by:

# from the root of the project
yarn --cwd=website install

Trouble shooting

Ubuntu issues

If you are using ubuntu, you might get errors as below:

Usage: yarn [options]
yarn: error: no such option: --cwd

which indicates your yarn is too old. You could install new version yarn with npm:

sudo apt install nodejs npm
sudo npm install -g yarn

Development server issues

If you run into TypeError: Cannot read property 'latest' of undefined error, try to remove both of website/node_modules and website/yarn.lock and re-run the install command. This issue has been reported here.

Local Development

In order to spin up the dev server locally for development:

yarn --cwd=website start

Build

To build the static site, from the root, run:

yarn --cwd=website build

you can then serve the built static website locally using:

yarn --cwd=website serve

Versioning

This site leverages the versioning mechanism provided by docusaurus, for details, check their docs about versioning here.

Deployment

This website is currently hosted on Netlify.

The deployment is automatically done when Pull Requests are merged to master branch. You may preview your PR before merging utilizing Netlify's preview feature.

Credits

This website is built on top of the wonderful Docusaurus along with a list of great open source projects, thanks to all of the contributors of them!

Acknowledgements (documentation, website and i18n)

  • Thanks to all contributors who have contributed to the development of Taichi documentation, community and website in the past. Please navigate to the members page of Taichi website to see the full acknowledgements. Specifically, we have built a avatar atlas for whoever have contributed to the taichi-docs-zh-cn translations:

  • Taichi中文文档及其社区、网站能够如此快速地成长，离不开每一位贡献者的工作和付出，感谢大家！请移步至 Taichi网站的社区成员页面来查看完整的鸣谢列表。特别地，我们在这里将曾参与过 taichi-docs-zh-cn 仓库翻译文档的贡献者特别列出。

contributors