增加项目文档库本地web浏览支持 (#27)

* save changes

* 保存更改

* 增加说明

* 修正文档标题

* fix typo (#24)

1.补全括号
2.badbmm -> baddbmm

* MathJax渲染BUG修复

* Update issue templates

* Update issue templates

* fix bug in d2l evaluate_accuracy

* 修复偶现数学公式渲染问题，兼容性增强

* 微调_格式，增加markdown在web端docsify的兼容性，同时也方便突出_字面意义

* 同步https://github.com/d2l-ai/d2l-zh该文档公式展示，推导清晰多了

* w,b为float32在macbook终端下编译出错，报RuntimeError: Expected object of scalar type Double but got scalar type Float for argument #2 'mat2'，修改成float64，更为兼容多数平台。

* fix bug: issue #29 #30

* 增加单个文档二级标题导航

* 增加单个文档内二三级导航动态合并到左边sidebar中，增加search，微调样式等

* 代码格式以及文辞微调

.gitignore

@@ -3,3 +3,4 @@
 *checkpoint.ipynb
 .mypy_cache*
 .vscode*
+.wwwdocs

Makefile

+wwwdocs:
+	bash script/prepare_wwwdocs.sh
+
+clean:
+	find . -name '*.pyc' -type f | xargs rm -rf
+	rm -rf .wwwdocs

docs/chapter02_prerequisite/2.2_tensor.md

@@ -135,7 +135,7 @@ torch.Size([5, 3])
     y.add_(x)
     print(y)
     ```
-    > **注：PyTorch操作inplace版本都有后缀"_", 例如`x.copy_(y), x.t_()`**
+    > **注：PyTorch操作inplace版本都有后缀`_`, 例如`x.copy_(y), x.t_()`**
 
 以上几种形式的输出均为：
 ```

docs/chapter03_DL-basics/3.1_linear-regression.md

@@ -61,9 +61,9 @@ $$
 
 $$
 \begin{aligned}
-w_1 &\leftarrow w_1 -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}} \frac{ \partial \ell^{(i)}(w_1, w_2, b)  }{\partial w_1}\\
-w_2 &\leftarrow w_2 -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}} \frac{ \partial \ell^{(i)}(w_1, w_2, b)  }{\partial w_2}\\
-b &\leftarrow b -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}} \frac{ \partial \ell^{(i)}(w_1, w_2, b)  }{\partial b}
+w_1 &\leftarrow w_1 -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}} \frac{ \partial \ell^{(i)}(w_1, w_2, b)  }{\partial w_1} = w_1 -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}}x_1^{(i)} \left(x_1^{(i)} w_1 + x_2^{(i)} w_2 + b - y^{(i)}\right),\\
+w_2 &\leftarrow w_2 -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}} \frac{ \partial \ell^{(i)}(w_1, w_2, b)  }{\partial w_2} = w_2 -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}}x_2^{(i)} \left(x_1^{(i)} w_1 + x_2^{(i)} w_2 + b - y^{(i)}\right),\\
+b &\leftarrow b -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}} \frac{ \partial \ell^{(i)}(w_1, w_2, b)  }{\partial b} = b -   \frac{\eta}{|\mathcal{B}|} \sum_{i \in \mathcal{B}}\left(x_1^{(i)} w_1 + x_2^{(i)} w_2 + b - y^{(i)}\right).
 \end{aligned}
 $$
 

docs/chapter03_DL-basics/3.2_linear-regression-scratch.md

@@ -113,8 +113,8 @@ tensor([[-1.4239, -1.3788],
 我们将权重初始化成均值为0、标准差为0.01的正态随机数，偏差则初始化成0。
 
 ``` python
-w = torch.tensor(np.random.normal(0, 0.01, (num_inputs, 1)), dtype=torch.float32)
-b = torch.zeros(1, dtype=torch.float32)
+w = torch.tensor(np.random.normal(0, 0.01, (num_inputs, 1)), dtype=torch.float64)
+b = torch.zeros(1, dtype=torch.float64)
 ```
 
 之后的模型训练中，需要对这些参数求梯度来迭代参数的值，因此我们要让它们的`requires_grad=True`。

docs/chapter03_DL-basics/3.5_fashion-mnist.md

@@ -26,7 +26,7 @@ import d2lzh_pytorch as d2l
 下面，我们通过torchvision的`torchvision.datasets`来下载这个数据集。第一次调用时会自动从网上获取数据。我们通过参数`train`来指定获取训练数据集或测试数据集（testing data set）。测试数据集也叫测试集（testing set），只用来评价模型的表现，并不用来训练模型。
 
 另外我们还指定了参数`transform = transforms.ToTensor()`使所有数据转换为`Tensor`，如果不进行转换则返回的是PIL图片。`transforms.ToTensor()`将尺寸为 (H x W x C) 且数据位于[0, 255]的PIL图片或者数据类型为`np.uint8`的NumPy数组转换为尺寸为(C x H x W)且数据类型为`torch.float32`且位于[0.0, 1.0]的`Tensor`。
-> 注意： 由于像素值为0到255的整数，所以刚好是uint8所能表示的范围，包括`transforms.ToTensor()`在内的一些关于图片的函数就默认输入的是uint8型，若不是，可能不会报错但的可能得不到想要的结果。所以，**如果用像素值(0-255整数)表示图片数据，那么一律将其类型设置成uint8，避免不必要的bug。** 本人就被这点坑过，详见[我的这个博客2.2.4节](https://tangshusen.me/2018/12/05/kaggle-doodle-reco/)。
+> 注意： 由于像素值为0到255的整数，所以刚好是uint8所能表示的范围，包括`transforms.ToTensor()`在内的一些关于图片的函数就默认输入的是uint8型，若不是，可能不会报错但可能得不到想要的结果。所以，**如果用像素值(0-255整数)表示图片数据，那么一律将其类型设置成uint8，避免不必要的bug。** 本人就被这点坑过，详见[我的这个博客2.2.4节](https://tangshusen.me/2018/12/05/kaggle-doodle-reco/)。
 
 ``` python
 mnist_train = torchvision.datasets.FashionMNIST(root='~/Datasets/FashionMNIST', train=True, download=True, transform=transforms.ToTensor())
@@ -47,7 +47,7 @@ print(len(mnist_train), len(mnist_test))
 我们可以通过下标来访问任意一个样本:
 ``` python
 feature, label = mnist_train[0]
-print(feature.shape, label)  # Channel x Height X Width
+print(feature.shape, label)  # Channel x Height x Width
 ```
 输出：
 ```

docs/chapter03_DL-basics/3.6_softmax-regression-scratch.md

@@ -153,7 +153,7 @@ print(evaluate_accuracy(test_iter, net))
 
 ## 3.6.7 训练模型
 
-训练softmax回归的实现跟[“线性回归的从零开始实现”](linear-regression-scratch.md)一节介绍的线性回归中的实现非常相似。我们同样使用小批量随机梯度下降来优化模型的损失函数。在训练模型时，迭代周期数`num_epochs`和学习率`lr`都是可以调的超参数。改变它们的值可能会得到分类更准确的模型。
+训练softmax回归的实现跟3.2（线性回归的从零开始实现）一节介绍的线性回归中的实现非常相似。我们同样使用小批量随机梯度下降来优化模型的损失函数。在训练模型时，迭代周期数`num_epochs`和学习率`lr`都是可以调的超参数。改变它们的值可能会得到分类更准确的模型。
 
 ``` python
 num_epochs, lr = 5, 0.1

docs/chapter03_DL-basics/3.7_softmax-regression-pytorch.md

@@ -53,13 +53,15 @@ class FlattenLayer(nn.Module):
 这样我们就可以更方便地定义我们的模型：
 ``` python
 from collections import OrderedDict
+
 net = nn.Sequential(
-        # FlattenLayer(),
-        # nn.Linear(num_inputs, num_outputs)
-        OrderedDict([
-          ('flatten', FlattenLayer()),
-          ('linear', nn.Linear(num_inputs, num_outputs))])
-        )
+    # FlattenLayer(),
+    # nn.Linear(num_inputs, num_outputs)
+    OrderedDict([
+        ('flatten', FlattenLayer()),
+        ('linear', nn.Linear(num_inputs, num_outputs))
+    ])
+)
 ```
 
 然后，我们使用均值为0、标准差为0.01的正态分布随机初始化模型的权重参数。

docs/chapter03_DL-basics/3.8_mlp.md

@@ -63,7 +63,7 @@ def xyplot(x_vals, y_vals, name):
 ```
 
 
-我们接下来通过`NDArray`提供的`relu`函数来绘制ReLU函数。可以看到，该激活函数是一个两段线性函数。
+我们接下来通过`Tensor`提供的`relu`函数来绘制ReLU函数。可以看到，该激活函数是一个两段线性函数。
 
 ``` python
 x = torch.arange(-8.0, 8.0, 0.1, requires_grad=True)

script/README.md

+# 前言
+
+1. 本目录用于构建项目HTML、PDF文档等使用，用于存放bash/python等脚本使用
+2. 所有构建入口请放入项目根目录下 `Makefile` 文件中调用
+
+Enjoy :))
\ No newline at end of file

script/prepare_wwwdocs.sh

+#!/usr/bin/env bash
+set -e
+
+docs=".wwwdocs"
+echo "本脚本将自动创建 ${docs} 目录"
+echo '初始化项目依赖时将使用 docsify 工具自动生成本地文档web访问文档'
+echo '本web文档为绿色创建，不会对现有项目产生副作用！不会产生产生git需要提交文件！'
+echo '请放心食用 :))'
+
+mkdir -p ${docs}
+
+echo '根据项目README.md自动生成目录文件 ......'
+cat README.md \
+  | awk '/^## 目录/ {print "* [前言]()"} \
+  	 /^### / && /\.md)$/ {print "* "substr($0, 5)} \
+  	 /^### / && ! /\.md)$/ {dot=$2; gsub(/\./, "\\.", dot); print "* "dot " " $3;} \
+  	 /^\[/ {print $0} /\.\.\./ {print "   * "$0}' \
+  | sed 's/https:\/\/github.com\/ShusenTang\/Dive-into-DL-PyTorch\/blob\/master\/docs\///g' \
+  | sed 's/^\[/   \* \[/g' \
+  > ${docs}/_sidebar.md
+
+echo '根据项目根目录下README.md以及docs/README.md合并生成项目所需${docs}导航 ......'
+sredme=`cat docs/README.md`
+cat README.md | awk -v sredme="${sredme}" '!/^### / && !/^\[/ && !/更新/ {print $0} /^## 目录/ {print sredme}' | sed 's/## 目录/## 说明/g' > ${docs}/README.md
+
+echo '生成 docsify 所需入口文件......'
+touch ${docs}/.nojekyll
+cat > ${docs}/index.html << EOF
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.js"></script>
+  <style>
+    .sidebar>h1 a {
+      font-size: 20px;
+      color: black;
+    }
+    .content {
+      padding-top: 5px;
+    }
+    .markdown-section {
+      padding-top: 10px;
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.\$docsify = {
+      loadSidebar: true,
+      maxLevel: 4,
+      subMaxLevel: 3,
+      auto2top: true,
+      alias: {
+        '/.*/_sidebar.md': '/_sidebar.md'
+      },
+      markdown: {
+        latexRender: katex.renderToString.bind(katex)
+      },
+      search: {
+      	placeholder: 'Type to search',
+      	noData: 'No Results!',
+        paths: 'auto',
+        depth: 6
+      },
+      plugins: [
+        function(hook, vm) {
+          hook.doneEach(function () {
+            window.MathJax.Hub.Queue(["Typeset", MathJax.Hub, document.getElementById('app')]);
+          })
+        }
+      ],
+      externalLinkTarget: '_target',
+      name: '《动手学深度学习》(PyTorch版)',
+      repo: 'https://github.com/ShusenTang/Dive-into-DL-PyTorch'
+    }
+  </script>
+  <script type="text/x-mathjax-config">
+    MathJax.Hub.Config({
+      extensions: ["tex2jax.js"],
+      jax: ["input/TeX", "output/HTML-CSS"],
+      tex2jax: {
+        inlineMath: [ ['\$','\$'], ["\\\(","\\\)"] ],
+        displayMath: [ ['\$$','\$$'], ["\\\[","\\\]"] ],
+        processEscapes: true,
+        skipTags: ["script", "noscript", "style", "textarea", "pre", "code", "a"]
+      },
+      "HTML-CSS": { fonts: ["TeX"] }
+    });
+  </script>
+  <script src="docsify.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
+  <script src="//unpkg.com/docsify-copy-code"></script>
+  <script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-python.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
+  <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+</body>
+</html>
+EOF
+
+echo '为各章节markdown文件以及图片建立软连接 ......'
+cd ${docs}
+ln -fs ../docs/chapter* .
+ln -fs ../img .
+cp ../script/docsify.js .
+
+port_used=`lsof -nP -iTCP -sTCP:LISTEN | grep 3000 | wc -l`
+if [[ ${port_used} -gt 0 ]]; then
+  echo '【警告】当前3000端口已被占用，请停止进程后再运行此脚本！'
+  exit 1
+fi
+
+echo '启动web server，稍后请在浏览器中打开：http://localhost:3000 ，即可访问 ......'
+if command -v docsify > /dev/null; then
+  docsify serve .
+else
+  #echo 'docsify-cli 没有安装，建议使用：npm i docsify-cli -g'
+  python -m SimpleHTTPServer 3000
+fi
\ No newline at end of file