3.4. 发布网站到GitHub¶

3.4.1. 什么是 GitHub Pages¶

3.4.2. 为你的工程库制作网站¶

本节讲述如何为自己的工程制作主页, 并附加API手册项目手册到网站, 以一个例子说明 [1]. 新建一个文件夹, 比如 pyml, 在该文件夹下存放你的工程源码和构建的文档, 以 pyml 为例, 新建 pyml 和 pyml-docs 文件夹分别用于存放项目和文档源码和用于发布的网站文件.

进入 pyml-docs 文件夹, 克隆你的库到该文件夹(如 git clone https://github.com/antsfamily/pyml.git html)

进入 html 文件夹, 此时该包依然为 master 分支, 使用如下命令为其创建一个 gh-pages 分支

git branch gh-pages
git symbolic-ref HEAD refs/heads/gh-pages  # auto-switches branches to gh-pages
rm .git/index
git clean -fdx
git branch

参考 _ChapterMakeManualAPI 小结生成 API文档, 注意修改 Makefile 文件中的输出文件夹路径 BUILDDIR 为上述 html 文件夹所在路径, 如果没有修改就手动将生成的 build/html 文件夹中的内容拷贝到 pyml-docs/html 文件夹下即可.

发布网站到GitHub: 执行更改提交即可

git add -A
git commit "update docs"
git push origin gh-pages

设置GitHub Pages: 浏览器登录你的 GitHub 账户, 找到你的库 (如 pyml ), 点击 settings --> GitHub Pages --> Source 选择 gh-pages branch 即可
访问你的网站: 默认的网址为 http://username.github.io/repositoryname, 你可以自定义域名, 比如本人的将 username.github.io 换为 iridescent.ink , 不过你需要买个域名.

目录树结构如下

└── pyml
    ├── pyml
    │   ├── docs
    │   │   ├── make.bat
    │   │   ├── Makefile
    │   │   └── source
    │   │       ├── conf.py
    │   │       ├── index.rst
    │   │       ├── modules.rst
    │   │       ├── pyml.math.rst
    │   │       ├── pyml.nn.rst
    │   │       ├── pyml.rst
    │   │       ├── _static
    │   │       └── _templates
    │   ├── LICENSE
    │   ├── pyml
    │   │   ├── __init__.py
    │   │   ├── math
    │   │   │   ├── geometry
    │   │   │   │   └── generate.py
    │   │   │   ├── __init__.py
    │   │   │   ├── __pycache__
    │   │   │   │   ├── __init__.cpython-36.pyc
    │   │   │   │   └── rand.cpython-36.pyc
    │   │   │   └── rand.py
    │   │   ├── nn
    │   │   │   ├── activations.py
    │   │   │   ├── __init__.py
    │   │   │   └── __pycache__
    │   │   │       ├── activations.cpython-36.pyc
    │   │   │       └── __init__.cpython-36.pyc
    │   │   └── __pycache__
    │   │       └── __init__.cpython-36.pyc
    │   └── README.md
    └── pyml-docs
        └── pyml
            ├── genindex.html
            ├── index.html
            ├── ...
            .
            .
            .

Footnotes

[1]	http://iridescent.ink/pyml/