diff --git a/docs-zh/config.ini b/docs-zh/config.ini new file mode 100644 index 0000000..f4a4a05 --- /dev/null +++ b/docs-zh/config.ini @@ -0,0 +1,70 @@ +# A demo for d2l-book. +[project] + +# The project name, used as the filename of the package and the PDF file. For +# example, if set to d2l-book, then will build d2l-book.zip and d2l-book.pdf +name = d2l-book + +# All author names +author = Mu Li + +release = 0.1.17 + +[html] + +# A list of links that is displayed on the navbar. A link consists of three +# items: name, URL, and a fontawesome icon +# (https://fontawesome.com/icons?d=gallery). Items are separated by commas. +header_links = PDF, https://book.d2l.ai/d2l-book.pdf, fas fa-file-pdf, + Github, https://github.com/d2l-ai/d2l-book, fab fa-github + +# The filename of the favicon +favicon = img/favicon.png + +html_logo = img/d2l-book.png + +[pdf] + +latex_logo = img/d2l.png + +[build] + +# A list of wildcards to indicate the markdown files that need to be evaluated as +# Jupyter notebooks. +notebooks = *.md */*.md + + +# A list of files, if anyone is modified after the last build, will re-build all +# documents. +dependences = config.ini + +# A list of files that will be copied to the build folder. +resources = img/ refs.bib + +# Specify the tabs, separated by ",". The first one will be the default tab. +tabs = python, numpy, cpython + +[deploy] + + +# Tracking ID for the HTML pages +google_analytics_tracking_id = UA-96378503-15 + +# The S3 bucket that all files will copy to +s3_bucket = s3://book.d2l.ai + +# [colab] + +# # The github repo to host the notebooks for colab, such as d2l-ai/d2l-book-colab +# # Also make sure that the machine's ssh key is added to github before running +# # "deploy" so that it can commit into d2l-ai/d2l-book-colab +# github_repo = d2l-ai/d2l-book-colab + +# # Colab cannot display SVG files with a relative fname or a github URL. You can +# # replace it with your website URL. For example: img, http://book.d2l.ai/_images +# # will "img/test.svg" to "http://book.d2l.ai/_images/test.svg" +# replace_svg_url = img, http://book.d2l.ai/_images + + +# [sagemaker] +# github_repo = d2l-ai/d2l-book-sagemaker diff --git a/docs-zh/demo.md b/docs-zh/demo.md new file mode 100644 index 0000000..88e6250 --- /dev/null +++ b/docs-zh/demo.md @@ -0,0 +1,20 @@ +# 构建本网站 + +您可能会发现建立这个网站是您项目的一个很好的起点。该网站的源代码可在以下位置获得 [demo/](https://github.com/d2l-ai/d2l-book/tree/master/demo). + +请确保你安装了`git`（可以通过 `conda install git` 安装）、`numpy` 和 `matplotlib` （可以通过 `pip install numpy matplotlib` 安装）。以下命令将下载源代码、评估所有笔记本并生成 `ipynb` 、 `html` 和 `pdf` 格式的输出。 + +```sh +git clone https://github.com/d2l-ai/d2l-book +cd d2l-book/demo +d2lbook build all +``` + +完成后，您可以在 `_build` 文件夹中检查结果。例如，现在这个页面会在 `_build/html/index.html`，PDF版本会在 `_build/pdf/d2l-book.pdf`，所有评估的笔记本都会在 `_build/eval/` 下。 +你可以单独生成以下特定的格式： + +```sh +d2lbook build eval # 评估笔记本并以 .ipynb 格式保存 +d2lbook build html # 构建 html 版本 +d2lbook build pdf # 构建 pdf 版本 +``` diff --git a/docs-zh/develop/index.md b/docs-zh/develop/index.md new file mode 100644 index 0000000..b3074ae --- /dev/null +++ b/docs-zh/develop/index.md @@ -0,0 +1,8 @@ +# Development Guide + +解释它是如何工作的。 + + +```toc +pipeline +``` diff --git a/docs-zh/develop/pipeline.md b/docs-zh/develop/pipeline.md new file mode 100644 index 0000000..3655cad --- /dev/null +++ b/docs-zh/develop/pipeline.md @@ -0,0 +1,22 @@ +# 构建管道 + + +![](../img/build.svg) + + +源文件是一些 markdown 文件。它们要么是纯粹的 markdown 文件，要么是以 markdown 格式保存、但已删除输出的 juypyter 笔记本。对于后者，我们可以直接使用 Jupyter 运行 `notedown` 插件来打开并编辑它们，然后在提交前运行 “Kernel -> Restart & Clear Output” 以清除输出。 + +然后我们的构建管道会运行以下步骤来构建结果。 + +1. 将 .md 文件转换为 .ipynb 文件并评估每个文件。我们使用 .md 文件作为源格式的原因是因为它很容易查看源文件的更改情况。我们每次都进行评估的原因是保证每个笔记本都是可执行的。这个评估步骤可能很耗时，我们可以 + - 假设每个 notebook 可以在 10 分钟内执行，我们可以使用多个 GPU 来加速执行。 + - 如果源.md文件在上次评估后没有变化，我们可以重新使用缓存的.ipynb文件，以避免再次执行。 + -我们使用多个进程并行运行 notebook 。 +1. 带有输出的 .ipynb 文件可以直接上传到 Github，因此用户可以克隆它以在本地或云端运行它们。我们还压缩所有文件，以便用户可以轻松下载。 +1. 然后将这些 .ipynb 文件转换为格式与 Sphinx 兼容的 .rst 文件。额外的预处理步骤用于图像/表格/引文参考。 +1. 使用 Sphinx 构建 .html 和 .pdf 文件 +1. 在线发布所有 .html/.pdf/.zip 文件，例如发布到 AWS S3 存储桶中。 + +## 多种实现方案 + +![](../img/multi-lang.svg) \ No newline at end of file diff --git a/docs-zh/img/build.graffle b/docs-zh/img/build.graffle new file mode 100644 index 0000000..41ca7f3 Binary files /dev/null and b/docs-zh/img/build.graffle differ diff --git a/docs-zh/img/build.svg b/docs-zh/img/build.svg new file mode 100644 index 0000000..cb6b366 --- /dev/null +++ b/docs-zh/img/build.svg @@ -0,0 +1,421 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs-zh/img/catdog.jpg b/docs-zh/img/catdog.jpg new file mode 100644 index 0000000..4471a71 Binary files /dev/null and b/docs-zh/img/catdog.jpg differ diff --git a/docs-zh/img/d2l-book.png b/docs-zh/img/d2l-book.png new file mode 100644 index 0000000..057df4c Binary files /dev/null and b/docs-zh/img/d2l-book.png differ diff --git a/docs-zh/img/d2l.png b/docs-zh/img/d2l.png new file mode 100644 index 0000000..c3a0000 Binary files /dev/null and b/docs-zh/img/d2l.png differ diff --git a/docs-zh/img/favicon.png b/docs-zh/img/favicon.png new file mode 100644 index 0000000..34cec8c Binary files /dev/null and b/docs-zh/img/favicon.png differ diff --git a/docs-zh/img/github_pages.png b/docs-zh/img/github_pages.png new file mode 100644 index 0000000..4613d4d Binary files /dev/null and b/docs-zh/img/github_pages.png differ diff --git a/docs-zh/img/jupyter.png b/docs-zh/img/jupyter.png new file mode 100644 index 0000000..507687f Binary files /dev/null and b/docs-zh/img/jupyter.png differ diff --git a/docs-zh/img/koebel.jpg b/docs-zh/img/koebel.jpg new file mode 100644 index 0000000..c9c52ce Binary files /dev/null and b/docs-zh/img/koebel.jpg differ diff --git a/docs-zh/img/lstm.svg b/docs-zh/img/lstm.svg new file mode 100644 index 0000000..2ade7dd --- /dev/null +++ b/docs-zh/img/lstm.svg @@ -0,0 +1,651 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs-zh/img/multi-lang.svg b/docs-zh/img/multi-lang.svg new file mode 100644 index 0000000..9bc2abc --- /dev/null +++ b/docs-zh/img/multi-lang.svg @@ -0,0 +1,205 @@ + + + + + + + + + + + + + + + + Produced by OmniGraffle 7.15.2 + 2020-05-12 19:46:54 +0000 + + + multi-lang + + Layer 1 + + + + + .md files + + + + + + + .ipynb files + + + + + + + .rst files + + + + + + + .pdf file + + + + + + + .pdf file + + + + + + + publish + + + + + + + publish + + + + + + + publish + + + + + + + + + + + + + + + + + + + + + + + + + + Step 1: + + + + + Step 2: + + + + + Step 3: + + + + + Step 4: + + + + + Step 5: + + + + + + + .ipynb files + + + + + + + + + + publish + + + + + + + + + + .rst files + + + + + + + + + + .html files + + + + + + + publish + + + + + + + + + + .ipynb files + + + + + + + + + + + + + + + + .rst files + + + + + + + + Step 4: + + + + + diff --git a/docs-zh/img/record-set.png b/docs-zh/img/record-set.png new file mode 100644 index 0000000..3366a41 Binary files /dev/null and b/docs-zh/img/record-set.png differ diff --git a/docs-zh/img/s3-acl.png b/docs-zh/img/s3-acl.png new file mode 100644 index 0000000..afb3890 Binary files /dev/null and b/docs-zh/img/s3-acl.png differ diff --git a/docs-zh/img/s3-web-hosting.png b/docs-zh/img/s3-web-hosting.png new file mode 100644 index 0000000..1b1745e Binary files /dev/null and b/docs-zh/img/s3-web-hosting.png differ diff --git a/docs-zh/index.md b/docs-zh/index.md new file mode 100644 index 0000000..b037e57 --- /dev/null +++ b/docs-zh/index.md @@ -0,0 +1,42 @@ +# D2L-Book： “动手做” 书籍的工具箱 + +The D2L Book (`d2lbook`)软件包可以帮助你构建和发布**一本带有Python代码的书，**或者是**带有教程的Python软件包文档**。你可以查看书的例子 [Dive into Deep Learning](https://d2l.ai/) ，或者是 python 软件包文档的例子 [AutoGluon](https://autogluon.mxnet.io/) 。 + +`d2lbook` 旨在满足以下两个要求： + +- 您的书中可能包含有**大量的 Python 代码**，并且您希望您的读者能够运行它们。或者您的软件包文档中有**多个实例教程**，并希望通过这些示例引导读者了解您的软件包的使用方法。这些代码应该是可运行和可维护的。 + +- 您希望同时发布 **HTML 网站和可打印的 PDF 版本** 两个版本。您希望网站应该是现代的、可搜索的和对移动端友好的，并且 PDF 版本应该与使用 LaTeX 编写的质量相同。 + + +为了实现上述目标， `d2lbook` 结合了 Python 中广泛使用的交互式环境 [Jupyter Notebook](https://jupyter.org/) 和 Python 软件包中事实上的通用文档构建系统 [Sphinx](http://www.sphinx-doc.org/en/master/) 。具体来说，它的主要特点包括 + +- 使用 [markdown](https://daringfireball.net/projects/markdown/) 编写您的内容 +- 一个最小的配置文件，用于自定义构建目标，以便您可以专注于内容。 +- 在发布之前会自动评估所有代码并获得其输出，以验证其正确性。我们只评估更新过的代码来节省成本。 +- 能够参考引用章节、图、表、方程式、函数和类别。 +- 通过 Github 或 AWS 发布您的网站的管道。 + +如果 `d2lbook` 不符合您的要求，您可以查看以下工具： + +- [Jupyter book](https://jupyterbook.org/intro)：与 `d2lbook` 非常相似，用于发布 Jupyter 笔记本。两个主要的设计差异是：1) `d2lbook` 鼓励你使用 markdown 文件格式，并在保存笔记本前删除所有代码输出。2) `d2lbook` 使用 Sphinx 而不是 Jupyter book 采用的 Jekyll 来构建文档。 Jekyll 更容易定制主题，而 Sphinx 对 PDF 和分析 Python 代码有更好的支持。注：目前 `Jupyter book` 也使用了 Sphinx 来构建文档。 +- [gitbook](https://www.gitbook.com/)：如果您不需要将它们作为 Jupyter 笔记本运行，那么使用这个来推送用 markdown 编写的书非常方便。 +- [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html)：这是一个Sphinx插件，用来评估和发布你的教程。它要求你知道如何使用 Sphinx 并以 `.py` 格式和 `rst` 风格编写你的教程。 + +```eval_rst +.. only:: html + + Table of Contents + ----------------- +``` + + +```toc +:numbered: +:maxdepth: 2 + +install +user/index +develop/index +``` + diff --git a/docs-zh/install.md b/docs-zh/install.md new file mode 100644 index 0000000..b25e5ea --- /dev/null +++ b/docs-zh/install.md @@ -0,0 +1,17 @@ +# Installation + + `d2lbook` 包已经在 macOS 和 Linux 平台上通过了测试。 (欢迎你为 windows 平台上的发行版本做出贡献). + +首先确保你有可用的 [pip](https://pip.pypa.io/en/stable/) 。 在选项中，我们建议使用 [conda](https://docs.conda.io/en/latest/miniconda.html) 安装 `pip` 不支持的库。 + +现在开始安装命令行界面 + +```sh +pip install git+https://github.com/d2l-ai/d2l-book +``` + +这就成功安装了 [d2lbook pip package](https://pypi.org/project/d2lbook/)， 但我们建议您直接安装在 Github 上的最新版本，因为它正在快速开发中。 + +为了构建 HTML 版本, 我们需要 [pandoc](https://pandoc.org/)。 你可以通过 `conda install pandoc` 安装它。 + +构建 PDF 版本需要[LibRsvg](https://wiki.gnome.org/Projects/LibRsvg) 去转换你的 SVG 格式图片(我们推荐的格式)，你可以通过 `conda install librsvg` 安装。当然，你你还需要有一个LaTeX发行版，例如 [Tex Live](https://www.tug.org/texlive/)，可用。 diff --git a/docs-zh/refs.bib b/docs-zh/refs.bib new file mode 100644 index 0000000..bc76abb --- /dev/null +++ b/docs-zh/refs.bib @@ -0,0 +1,44 @@ +@inproceedings{krizhevsky2012imagenet, + title={Imagenet classification with deep convolutional neural networks}, + author={Krizhevsky, Alex and Sutskever, Ilya and Hinton, Geoffrey E}, + booktitle={Advances in neural information processing systems}, + pages={1097--1105}, + year={2012} +} + +@inproceedings{he2016deep, + title={Deep residual learning for image recognition}, + author={He, Kaiming and Zhang, Xiangyu and Ren, Shaoqing and Sun, Jian}, + booktitle={Proceedings of the IEEE conference on computer vision and pattern recognition}, + pages={770--778}, + year={2016} +} + +@article{devlin2018bert, + title={Bert: Pre-training of deep bidirectional transformers for language understanding}, + author={Devlin, Jacob and Chang, Ming-Wei and Lee, Kenton and Toutanova, Kristina}, + journal={arXiv preprint arXiv:1810.04805}, + year={2018} +} + +@TechReport{mitchell80, + author = "T. M. Mitchell", + title = "The Need for Biases in Learning Generalizations", + institution = "Computer Science Department, Rutgers University", + year = "1980", + address = "New Brunswick, MA", +} + +@InCollection{Newell81, + author = "A. Newell and P. S. Rosenbloom", + title = "Mechanisms of Skill Acquisition and the Law of + Practice", + booktitle = "Cognitive Skills and Their Acquisition", + pages = "1--51", + publisher = "Lawrence Erlbaum Associates, Inc.", + year = "1981", + editor = "J. R. Anderson", + chapter = "1", + address = "Hillsdale, NJ", + eprint = {arXiv:1510.01797}, +} diff --git a/docs-zh/user/build.md b/docs-zh/user/build.md new file mode 100644 index 0000000..9cd6dcd --- /dev/null +++ b/docs-zh/user/build.md @@ -0,0 +1,96 @@ +# 构建 + +本节我们将解释构建项目的各种选项。这些选项可分为四类： + +1. 完整性检查 + - `d2lbook build linkcheck` 将检查是否所有内部和外部链接都可以访问。 + - `d2lbook build outputcheck` 将检查是否没有 notebook 将包含代码输出 +1. 构建结果 + - `d2lbook build html`: 将构建 HTML 版本到 `_build/html` + - `d2lbook build pdf`: 将构建 PDF 版本到 `_build/pdf` + - `d2lbook build pkg`: 构建一个包含所有 `.ipynb` 格式 Jupyter notebook 的 zip 文件 +1. 附加功能 + - `d2lbook build colab`: 将所有 notebook 转换为可以在 Google Colab 上运行的文件并保存到 `_build/colab`。更多信息请参见 :numref:`sec_colab` + - `d2lbook build lib`: 构建一个 Python 包，以便我们可以在其他笔记本中重用代码。更多信息请参见 XXX 。 +1. 内部阶段，通常是自动触发的。 + - `d2lbook build eval`: 评估所有笔记本并将它们作为 `.ipynb` 笔记本保存到`_build/eval` + - `d2lbook build rst`: 将所有笔记本转换为 `rst` 文件并在 `_build/rst` 中创建一个 Sphinx 项目 + + +## 构建时的缓存 + +我们鼓励您使用内置的自动化评估您的笔记本以获得代码单元结果，而不是将这些结果保存在源文件中，原因有两个： + 1. 这些结果使代码审查变得困难，尤其是当它们由于数值精度或随机数生成器而具有随机性时。 + + 1. 一段时间未评估的笔记本可能因升级包而损坏。 + +但是评估会在构建过程中产生额外的开销。因此，我们建议将每个笔记本的运行时间限制在几分钟内。并且 `d2lbook` 将重用之前构建的并且只评估修改后的笔记本。 + +例如，由于训练神经网络，[Dive into Deep Learning](https://d2l.ai) 中的笔记本（部分）在 GPU 机器上的平均运行时间约为 2 分钟。它包含 100 多个笔记本，这使得总运行时间多达 2-3 小时。但是，实际上，每次代码更改只会修改其中几个笔记本，因此 [构建时间](http://ci.d2l.ai/blue/organizations/jenkins/d2l-en/activity) 通常不到 10 分钟。 + +让我们看看它是如何工作的。首先我们像这一节创建一个项目 :numref:`sec_create`. + +```{.python .input} +!mkdir -p cache +``` + +```{.python .input} +%%writefile cache/index.md +# My Book + +通过 `d2lbook`创建 my book 的起始页 + +````toc +get_started +```` +``` + +```{.python .input} +%%writefile cache/get_started.md +# 开始 + +首先请安装我最喜欢的包 `numpy`。 +``` + +```{.python .input} +!cd cache; d2lbook build html +``` + +你可以看到 `index.md` 被评估了。 （虽然它不包含代码，但可以将其作为 Jupyter notebook 评估。）如果再次构建，我们将看到不会评估任何 notebook 。 + +```{.python .input} +!cd cache; d2lbook build html +``` + +现在让我们修改 `get_started.md` ，你会看到它会被重新评估，但不包括 `index.md` 。 + +```{.python .input} +%%writefile cache/get_started.md +# 开始写入的内容 + +首先请安装我最喜欢的包 `numpy>=1.18`. +``` + +```{.python .input} +!cd cache; d2lbook build html +``` + +触发从头开始重新构建的一种方法是删除 `_build/eval` 中保存的 notebook ，或者直接删除 `_build` 。另一种方法是重新指定一些依赖项。例如，在下面的单元格中，我们将 `config.ini` 添加到依赖项中。每次修改 config.ini 都会使所有 notebook 的缓存失效，并触发从头开始重新构建。 + + +```{.python .input} +%%writefile cache/config.ini + +[build] +dependencies = config.ini +``` + +```{.python .input} +!cd cache; d2lbook build html +``` + +最后，让我们清理一下我们的工作区。 + +```{.python .input} +!rm -rf cache +``` diff --git a/docs-zh/user/code.md b/docs-zh/user/code.md new file mode 100644 index 0000000..701bdfc --- /dev/null +++ b/docs-zh/user/code.md @@ -0,0 +1,49 @@ +# 代码单元格 +:label:`sec_code` + +## 最大行长（maximum line length） + +我们建议您将代码的最大行长限制在 78 内以避免 PDF 中的自动换行。您可以在 [nbextensions](https://github.com/ipython-contrib/jupyter_contrib_nbextensions) 中启用标尺扩展，以便在编写代码时在 Jupyter 中添加可视垂直线。 + +```{.python .input} +'-' * 78 +``` + +## 隐藏源代码和输出 + +我们可以通过在单元格中添加注释行 `# Hide code` 来隐藏代码单元格的源代码。我们还可以使用 `# Hide outputs` 隐藏代码单元格的输出 + +举个例子，这里是正常的代码单元: + +```{.python .input} +1+2+3 +``` + +让我们把源代码隐藏起来 + +```{.python .input} +# Hide code +1+2+3 +``` + +还可以尝试一下隐藏输出 + +```{.python .input} +# Hide outputs +1+2+3 +``` + +## 绘图 +我们建议您使用 `svg` 格式来绘制图形。比如下面的代码调用了 `matplotlib` 来绘图 + +```{.python .input n=3} +%matplotlib inline +from IPython import display +from matplotlib import pyplot as plt +import numpy as np + +display.set_matplotlib_formats('svg') + +x = np.arange(0, 10, 0.1) +plt.plot(x, np.sin(x)); +``` diff --git a/docs-zh/user/code_tabs.md b/docs-zh/user/code_tabs.md new file mode 100644 index 0000000..77c0f30 --- /dev/null +++ b/docs-zh/user/code_tabs.md @@ -0,0 +1,79 @@ +# Group Code Blocks into Tabs + +下面是一个例子，显示了如何将代码块分组为三个选修卡。 + +## 例子 + +让我们实现$a+b$。我们先展示说明，然后演示代码。 + +:begin_tab:`python` +你需要安装先 python + +:end_tab: + +:begin_tab:`numpy` +你可以通过以下命令安装 numpy +```bash +pip install numpy +``` +:end_tab: + +:begin_tab:`cpython` +请安装 cpython +:end_tab: + + +```{.python .input} +a = [1,1,1] +b = [2,2,2] +[ia+ib for ia, ib in zip(a,b)] +``` + +```{.python .input} +#@tab numpy +import numpy as np +a = np.ones(3) +b = np.ones(3)*2 +a + b +``` + +```{.python .input} +#@tab cpython +# 只是一个占位符 +print(1+2) +``` + +下一步让我们展示 $a - b$ + +```{.python .input} +a = [1,1,1] +b = [2,2,2] +[ia-ib for ia, ib in zip(a,b)] +``` + +```{.python .input} +#@tab numpy +a = np.ones(3) +b = np.ones(3)*2 +a - b +``` + +```{.python .input} +#@tab cpython +# 只是一个占位符 +print(1-2) +``` + +## 使用方法 + + + +要启用多选项卡，首先在 `config.ini` 文件中配置 `tabs` 条目。举个例子，这里我们配置选项为 `tabs = python, numpy, cpython`。 `python` 是默认选项卡。要指定不属于默认选项卡 （python） 的代码块，请在代码块的第一行添加 `#@tab` ，后跟选项卡名称（不区分大小写）。 + +有时这些代码块会相互冲突。我们可以一次激活一个选项卡，这样就只有属于该选项卡的代码块才能在 Jupyter 中进行评估。例如： + +```bash +d2lbook activate default user/code_tabs.md # activate the default tab +d2lbook activate numpy user/code_tabs.md # activate the numpy tab +d2lbook activate all user/code_tabs.md # activate all tabs +``` diff --git a/docs-zh/user/colab.md b/docs-zh/user/colab.md new file mode 100644 index 0000000..9af0beb --- /dev/null +++ b/docs-zh/user/colab.md @@ -0,0 +1,2 @@ +# Colab +:label:`sec_colab` diff --git a/docs-zh/user/create.md b/docs-zh/user/create.md new file mode 100644 index 0000000..6056adf --- /dev/null +++ b/docs-zh/user/create.md @@ -0,0 +1,85 @@ +# 创建你的项目 +:label:`sec_create` + +让我们以来自 scratch 的一个简单项目开始. + +## Scratch 的羡慕 + +首先我们为我们的项目创建一个文件夹。 + +```{.python .input n=1} +!mkdir -p mybook +``` + +然后创建两个页面。 `index.md` 是包含目录 (table of content，TOC) 的索引页，其中包含其他页 `get_started.md` 。请注意，TOC 是在带有标签 “toc” 的代码块中定义的。如果您熟悉 Sphinx，您会发现它类似于 Sphinx 中的 TOC 定义。请参考 :numref:`sec_markdown` 来了解更多 `d2lbook` 添加到 markdown 中的扩展 。另外请注意，我们使用内置魔法命令 `writefile` 将代码块保存到 [Jupyter] (https://ipython.readthedocs.io/en/stable/interactive/magics.html) 提供的文件中。 + +```{.python .input n=2} +%%writefile mybook/index.md +# My Book + +以 `d2lbook` 构建的项目—— mybook 的起始页。 + +````toc +get_started +```` +``` + +```{.python .input n=3} +%%writefile mybook/get_started.md +# Getting Started + +Please first install my favorite package `numpy`. +``` + +现在让我们构建 html 版本。 + +```{.python .input n=4} +!cd mybook && d2lbook build html +``` + +HTML 索引页 可以在 `mybook/_build/html/index.html` 目录中找到. + +## 构造配置 + +你可以通过根文件夹上的 `config.ini` 来自定义构建结果和发布方式。 + +```{.python .input n=5} +%%writefile mybook/config.ini + +[project] +# Specify the PDF filename to mybook.pdf +name = mybook +# Specify the authors names in PDF +author = Adam Smith, Alex Li + +[html] +# Add two links on the navbar. A link consists of three +# items: name, URL, and a fontawesome icon. Items are separated by commas. +header_links = PDF, https://book.d2l.ai/d2l-book.pdf, fas fa-file-pdf, + Github, https://github.com/d2l-ai/d2l-book, fab fa-github +``` + +让我们清除并重新构建。 + +```{.python .input} +!cd mybook && rm -rf _build && d2lbook build html +``` + +如果再次打开 `index.html`，你将在导航栏上看到两个链接。 + +让我们构建 PDF 输出，您会在输出日志中找到 `Outputwritten on mybook.pdf (7 pages).`。 + +```{.python .input} +!cd mybook && d2lbook build pdf +``` + +我们将在以下部分介绍更多配置选项。您可以查看 [default_config.ini](https://github.com/d2l-ai/d2l-book/blob/master/d2lbook/config_default.ini) 了解所有配置选项及其默认值。还可以查看这些示例的 `config.ini` + +- [This website](https://github.com/d2l-ai/d2l-book/blob/master/docs/config.ini) +- [Dive into Deep Learning](https://github.com/d2l-ai/d2l-en/blob/master/config.ini) + +最后，让我们清理一下我们的工作区。 + +```{.python .input} +!rm -rf mybook +``` diff --git a/docs-zh/user/deploy.md b/docs-zh/user/deploy.md new file mode 100644 index 0000000..22e2e9d --- /dev/null +++ b/docs-zh/user/deploy.md @@ -0,0 +1,112 @@ +# 部署 + +您可以将构建的结果复制到您喜欢的、可以在线展示内容的任何地方。除此之外，`d2lbook` 提供了两种部署构建结果的方法：通过 [Github](http://github.com/) 或通过 [AWS](https://aws.amazon.com/) 部署。 + +## 通过 Github 部署 + +[Github Pages](https://pages.github.com/) 允许我们通过 Github repo 托管一个网站。为此，我们首先需要创建一个 github repo，例如我们创建了 [d2l-ai/d2l-book-deploy-demo](https://github.com/d2l-ai/d2l-book-deploy-demo ) 来作为例子。然后在 `Settings -> GitHub Pages` 中从 master 分支启用服务。您将获得一个 URL 来访问它。此示例为 [d2l-ai.github.io/d2l-book-deploy-demo](https://d2l-ai.github.io/d2l-book-deploy-demo/)。您可以向 `README.md` 添加任何内容，但这些内容不会显示在网站上。 + +![Enable serving from master branch at Github](../img/github_pages.png) +:width:`400px` + +现在让我们创建一个指定了 `[deploy] github_repo` 的项目并构建 HTML 和 PDF。多亏了 LaTeX，你会看到大量的日志信息，更准确地说，是 LaTex 的排版引擎 `xelatex`。 + +```{.python .input} +!mkdir -p deploy +``` + +```{.python .input} +%%writefile deploy/index.md +# 部署 d2lbook 的 demo + +这是一个部署在 Github 上的 demo 。 + +````toc +get_started +```` +``` + +```{.python .input} +%%writefile deploy/get_started.md +# 开始 + +首先请安装我最喜欢的包 `numpy`. +``` + +```{.python .input} +%%writefile deploy/config.ini +[project] +name = deply-demo + +[html] +header_links = PDF, https://https://d2l-ai.github.io/d2l-book-deploy-demo/deply-demo.pdf, fas fa-file-pdf + +[deploy] +github_repo = d2l-ai/d2l-book-deploy-demo +``` + +```{.python .input} +!cd deploy; d2lbook build html pdf +``` + +要部署到 Github，您需要将机器的 [SSH 密钥导入到 Github](https://github.com/settings/keys)。否则，您可能需要输入您的帐户和密码。完成后，您可以在一两分钟内在线评估结果。对于该示例，URL 为 [/d2l-ai.github.io/d2l-book-deploy-demo/](https://d2l-ai.github.io/d2l-book-deploy-demo/)。 + +```{.python .input} +!cd deploy; d2lbook deploy html pdf +``` + +最后，让我们清理一下我们的工作区。 + +```{.python .input} +!rm -rf deploy +``` + +## 通过 AWS 部署 + +另一个受支持的选项是通过 AWS 部署。这个选项提供了更大的灵活性，但需要您了解 AWS 的基本用法。 + +我们推荐以下部署过程： + +1. 将结果复制到 [S3](https://aws.amazon.com/s3/). +2. 通过使用 [CloudFront](https://aws.amazon.com/cloudfront/) 与 [CDN](https://en.wikipedia.org/wiki/Content_delivery_network) 服务以减少延迟。 +3. 在 [Route 53](https://aws.amazon.com/route53/) 购买并添加定制域名。 + +现在让我们一个接一个地走过这三个步骤。在开始之前，您需要拥有一个有效的AWS帐户，并通过运行 `aws configure` 输入 [AWS访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) （`AWS access key`）。 + + +首先，创建一个 S3 存储桶。您可以使用目标域名作为您的存储桶名称。举个例子，加入这个站点部署在 book.d2l.ai ，那么我们把创建的这个存储桶命名为 `book.d2l.ai` 。此外，我们需要在创建此存储桶时禁用通过 ACL 阻止公共访问（disable blocking public access through ACLs），请参阅 :numref:`fig_s3-acl` 并启用静态网站托管，请参阅 :numref:`fig_s3-web-hosting` 。然后您将获得一个 URL 来访问此存储桶。在我们的示例中，它是 http://book.d2l.ai.s3-website-us-west-2.amazonaws.com/ 。 + + +![Disable blocking public access through ACLs](../img/s3-acl.png) + +:label:`fig_s3-acl` +:width:`500px` + +![Enable static web hosting](../img/s3-web-hosting.png) + +:label:`fig_s3-web-hosting` +:width:`500px` + +第二步，通过指定以下选项，创建一个新的 CloudFront 发行版： +- 源域名：之前的 S3 URL，不带 `http://` ， 例如 `book.d2l.ai.s3-website-us-west-2.amazonaws.com` +- 默认根对象： `index.html` +- [optional] 待用域名 （CNAMEs）： 您的目标域名，例如 `book.d2l.ai` +- [optional] SSL 证书：您可以在 [证书管理器](https://aws.amazon.com/certificate-manager/) 中创建一个，然后选择使用它。 + +几分钟后，我们将获得诸如 `d1y0wi2ibwmzrt.cloudfront.net` 之类的域名。 + +第三步，您可以在 Route 53 购买域或将 Route 53 的 DNS 添加到现有域中。之后，创建一个“托管区域”，然后创建一个以 CoundFront 域名为别名目标的 Type-A 记录集，示例参见 :numref:`fig_record-set` 。 + +![Create a Record Set](../img/record-set.png) + +:label:`fig_record-set` +:width:`350px` + +当您完成后，在 `config.ini` 的以下条目中指定您的 S3 存储桶名称。 + +```bash +[deploy] +s3_bucket = s3://book.d2l.ai +``` + +每次运行 `d2lbook deploy` 时，所有结果都会同步到此存储桶并自动部署。请注意，由于我们启用了 CDN，任何新的更改都可能需要一段时间才能显示在您的 URL 中（例如 http://book.d2l.ai）。但是您可以检查 S3 存储桶 URL（例如 http://book.d2l.ai.s3-website-us-west-2.amazonaws.com）以便立即查看更改。 diff --git a/docs-zh/user/edit.md b/docs-zh/user/edit.md new file mode 100644 index 0000000..100508a --- /dev/null +++ b/docs-zh/user/edit.md @@ -0,0 +1,38 @@ +# 编辑源文件 + +无论是纯文本文件还是 Jupyter notebook，我们都建议您将其保存为 markdown 文件。如果是 Jupyter notebook ，可以在保存前清空输出，方便代码审查和版本控制。 + +您可以使用自己喜欢的 markdown 编辑器，例如[Typora](https://www.typora.io/)，用来直接编辑 markdown 文件。我们扩展了 markdown 以支持附加功能，例如图像/表格标题和引用参考文献，请参阅 :numref:`sec_markdown` 了解更多详细信息。对于 Jupyter notebook 来说，一个 Jupyter 源代码块会被放置在一个带有 `{.python .input}` 标签的 markdown 代码块中，例如， + +```` +```{.python .input} +print('this is a Jupyter code cell') +``` +```` + +我们另一种推荐的做法是直接使用 Jupyter 编辑 markdown 文件，尤其是它包含代码块的时候。 Jupyter 默认的文件格式是 ipynb ，我们可以使用 notedown 插件让 Jupyter 打开并保存 markdown 文件。 + +你可以通过以下命令安装它： + +```bash +pip install mu-notedown +``` + +（`mu-notedown` 是 [notedown](https://github.com/aaren/notedown) 的一个分支，与源文件存在几个修改。安装之前，你可能需要先卸载原来的 `notedown`。） + +如果要在运行 Jupyter Notebook 时默认打开 “notedown” 插件，请执行以下操作：首先，生成一个 Jupyter Notebook 配置文件（如果已经生成，则可以跳过此步骤）。 + +```bash +jupyter notebook --generate-config +``` + +然后，在 Jupyter 笔记本电脑配置文件的末尾添加以下行（对于Linux/macOS，通常位于路径 `~/.Jupyter/Jupyter_Notebook_config.py` ）： + +```bash +c.NotebookApp.contents_manager_class = 'notedown.NotedownContentsManager' +``` + +接下来重新启动 Jupyter，您现在应该可以在 Jupyter 中将这些 markdown 作为 Jupyter notebook 打开。 + +![Use Jupyter to edit :numref:`sec_create`](../img/jupyter.png) +:width:`500px` diff --git a/docs-zh/user/index.md b/docs-zh/user/index.md new file mode 100644 index 0000000..b83b28a --- /dev/null +++ b/docs-zh/user/index.md @@ -0,0 +1,22 @@ +# 使用手册 + +在这个部分，我们会讲解： + +1. 如何去创建一个项目 +1. 如何去构建和展示一个文档 +1. 不同的配置选项 +1. Markdown 和 code 实例 + +```toc +:maxdepth: 2 + +create +edit +build +deploy +markdown +code +code_tabs +slides +colab +``` diff --git a/docs-zh/user/markdown.md b/docs-zh/user/markdown.md new file mode 100644 index 0000000..42447cb --- /dev/null +++ b/docs-zh/user/markdown.md @@ -0,0 +1,186 @@ +# Markdown 单元格 +:label:`sec_markdown` + + +`d2lbook` 提供了超出 Jupyter 中普通 markdown 支持的附加功能。 + +## 目录 + +您可以使用 `toc` 代码块来指定目录。这里 `:maxdepth: 2` 表示显示两级目录，`:numbered:` 表示在每个部分前添加编号（默认不启用）。另外请注意，您不需要指定文件扩展名。 + +````` +```toc +:maxdepth: 2 +:numbered: + +guide/index +``` +````` + + +## 图片 + + +我们可以将图片标题放在 `[]` 块中。此外，我们可以使用 `:width:` 后跟一个值用于在内联块中指定图像宽度，类似地使用 `:height:` 表示高度。 + +``` +![Estimating the length of a foot](../img/koebel.jpg) +:width:`400px` +``` + + +![Estimating the length of a foot](../img/koebel.jpg) +:width:`400px` + + +### SVG 图像 + + +我们建议您尽可能多地使用 SVG 图像。它的图像边缘锐利，而且尺寸很小。但是由于 Latex 不支持 SVG 图像，如果要构建 PDF 输出，则需要安装 `rsvg-convert`。在 Macos 上，您可以简单地运行命令 `brew install librsvg` ；对于 Ubuntu，您可以运行 `sudo apt-get install librsvg2-bin`。 + +![A LSTM cell in SVG](../img/lstm.svg) + +## 表格 + +您可以在表格前插入表格标题，方法是以 `:` 开头。请注意，您需要在标题和表格本身之间留下一条空行。 + +``` +: The number is computed by $z_{ij} = \sum_{k}x_{ik}y_{kj}$. + +| Year | Number | Comment | +| --- | --- | --- | +| 2018 | 100 | Good year | +| 2019 | 200 | Even better, add something to make this column wider | +``` + + +: The number is computed by $z_{ij} = \sum_{k}x_{ik}y_{kj}$. + +| Year | Number | Comment | +| --- | --- | --- | +| 2018 | 100 | Good year | +| 2019 | 200 | Even better, add something to make this column wider | + +如果表格标题编号显示不正确，您可能需要将 `pandoc` 更新到最新版本。 + +## 交叉引用 + +我们经常想在书中引用章节、图片、表格和方程式。 + +### 引用章节 +:label:`my_sec3` + +我们可以在章节标题后放置一个标签，以允许该章节被这个标签引用。标签的格式是在一个内嵌的代码块中使用 `:label:` 跟上其标签名称。 + +``` +### Referencing Sections +:label:`my_sec3` +``` + + +然后我们可以通过在内联代码块中的使用 `:ref:` 后跟该标签的名称，来引用该部分 + +``` +:ref:`my_sec3` 演示如何引用章节 +``` + +:ref:`my_sec3` 演示如何引用章节 + + +请注意，它会显示出引用部分的标题，并带有可单击的链接。我们还可以通过将 `:num:` 更改为 `:numref:` 来使用带编号的版本，例如 :numref:`my_sec3`。 + +如果标签不正确，比如我们把 `my_sec2` 放在这里，构建日志里将出现 `warning` ，例如 + +``` +WARNING: undefined label: my_sec2 +``` + +您可以通过在 `config.ini` 中设置 `warning_is_error = True` 将这个 `warning` 改为 `error` 。 + +此外，我们也可以从其他文件交叉引用标签，例如 :numref:`sec_code` 。这也适用于图片、表格和方程式。 + + +### 引用图片 + +类似地，我们可以给一个图片加上标签，并在以后引用它。 + +``` +![A nice image with a cat and a dog.](../img/catdog.jpg) +:width:`300px` +:label:`img_catdog` + +我们可以看看 :numref:`img_catdog` ，这里面是一只猫和一只狗。 +``` + + +![A nice image with a cat and a dog.](../img/catdog.jpg) +:width:`300px` +:label:`img_catdog` + +我们可以看看 :numref:`img_catdog` ，这里面是一只猫和一只狗。 + +### 引用表格 + +``` +:这是一个很长的表格标题。它将分成几行。并且还包含一个数学方程式。 $z_{ij} = \sum_{k}x_{ik}y_{kj}$. + +| Year | Number | Comment | +| --- | --- | --- | +| 2018 | 100 | Good year | +:label:`table` + +Refer to :numref:`table` + +``` + + +:这是一个很长的表格标题。它将分成几行。并且还包含一个数学方程式。 $z_{ij} = \sum_{k}x_{ik}y_{kj}$. + +| Year | Number | Comment | +| --- | --- | --- | +| 2018 | 100 | Good year | +:label:`table` + +Refer to :numref:`table` + +### 引用方程式 + +这里的区别是我们需要使用 `eqlabel` 而不是 `label`。例如： + +``` +$$\hat{\mathbf{y}}=\mathbf X \mathbf{w}+b$$ +:eqlabel:`linear` + + +在 :eqref:`linear` 中，我们定义了一个数学模型。 +``` + + +$$\hat{\mathbf{y}}=\mathbf X \mathbf{w}+b$$ +:eqlabel:`linear` + +在 :eqref:`linear` 中，我们定义了一个数学模型。 + + +## 引用文献 + + + +首先把你的 bib 文件放在某个地方。所有引用都将显示在它在 HTML 中插入的位置。但在 PDF 中，所有参考文献都将移至文档末尾。然后我们可以通过`:cite:`引用一篇论文。 Multipel 论文可以用逗号分隔（注意不能有空格） + +``` + +深度学习的突破源于 :cite:`krizhevsky2012imagenet` 对于计算机视觉的工作，这一领域有丰富的后续研究，如 :cite:`he2016deep` 。NLP也在迎头赶上，最近的工作:cite:`devlin2018bert` 体现出了明显的进步。 +两个引用放在一起 :cite:`he2016deep,devlin2018bert` 。单个作者论文的引用 :cite:`mitchell80` ，两个作者论文的引用 :cite:`Newell81` + +:bibliography:`../refs.bib` +``` + + +深度学习的突破源于 :cite:`krizhevsky2012imagenet` 对于计算机视觉的工作，这一领域有丰富的后续研究，如 :cite:`he2016deep` 。NLP也在迎头赶上，最近的工作:cite:`devlin2018bert` 体现出了明显的进步。 + +同时引用两篇文献 :cite:`he2016deep,devlin2018bert` 。单个作者论文的引用 :cite:`mitchell80` ，两个作者论文的引用 :cite:`Newell81` + +## 参考文献 + +:bibliography:`../refs.bib` diff --git a/docs-zh/user/slides.md b/docs-zh/user/slides.md new file mode 100644 index 0000000..21ab3d0 --- /dev/null +++ b/docs-zh/user/slides.md @@ -0,0 +1,90 @@ +# 创建幻灯片 + + +我们可以标记一个笔记本，然后从该笔记本中创建幻灯片。例如，这里是从 markdown 的 [源文件](https://github.com/d2l-ai/d2l-en/blob/master/chapter_preliminaries/ndarray.md) 中生成的 [幻灯片](https://nbviewer.jupyter.org/format/slides/github/d2l-ai/d2l-pytorch-slides/blob/main/chapter_preliminaries/ndarray.ipynb#/) 。让我们通过下面的例子来解释如何做到这一点。这是一个带有标记的 markdown 文件，用来生成幻灯片。 + +````md +# Data Manipulation + +## Getting Started + +To start, we can use `arange` to create a row vector `x` +containing the first 12 integers starting with 0, +though they are created as floats by default. + +(**A tensor represents a (possibly multi-dimensional) array of numerical values. We can access a tensor's *shape*.**) + + +```{.python .input} +import numpy as np + +x = np.arange(12) +x +``` + +[**Many**] more (**operations can be applied elementwise,**) +including unary operators like exponentiation. +(~~e.g. `exp`~~) + +```{.python .input} +np.exp(x) +``` + +(**Even when shapes differ, we can still perform elementwise operations**) +by invoking the *broadcasting mechanism*. + + +```{.python .input} +a = np.arange(3).reshape(3, 1) +b = np.arange(2).reshape(1, 2) +a, b +``` + +```` + +上面的代码块将生成 2 张幻灯片。第一张幻灯片包含以下内容： + +````md +# Data Manipulation + +A tensor represents a (possibly multi-dimensional) array of numerical values. We can access a tensor's *shape*. + +```{.python .input} +import numpy as np + +x = np.arange(12) +x +``` +```` + +您可以看到我们自动复制了一级标题和代码块。 +此外，我们复制了 `(**` 和 `**)` 之间的文本，而删除了所有其他的文本。 + +第二张幻灯片包含以下内容： + +````md +Many operations can be applied elementwise, +e.g. `exp` + +```{.python .input} +np.exp(x) +``` + +Even when shapes differ, we can still perform elementwise operations + +```{.python .input} +a = np.arange(3).reshape(3, 1) +b = np.arange(2).reshape(1, 2) +a, b +``` +```` + +首先，你可以看到 +(`[**`, `**]`)， +(`(**`, `**)`) 和 +(`(~~`, `~~)`) 这三个部分之间的所有文本被保留了。 +在这里， `[` 表示开始一张新幻灯片，而 `(` 表示继续当前幻灯片。 +一级标题 (`[**`, `**]`) 内的文本将开始一张新幻灯片，因此我们在上一个块中使用了`(` 来连接两段标题的文本 。 +另外，`~~` 表示文本只会出现在幻灯片中，不会在普通 notebook 、html 或 pdf 中出现。 + +其次，我们没有在最后一个代码块之前开始新的幻灯片，没有一级标题，也没有 (`[**`, `**]`) 对，所以最后两个代码块合并到同一张幻灯片。