This is an automated email from the ASF dual-hosted git repository.
jxie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-mxnet.git
The following commit(s) were added to refs/heads/master by this push:
new 02e805f Update doc README (#7797)
02e805f is described below
commit 02e805fddb4a108de09d4fde78b16da92164af16
Author: Yao Wang <[email protected]>
AuthorDate: Thu Sep 7 23:38:41 2017 -0700
Update doc README (#7797)
* Update doc README
* Fix
* More fix
* Add community into search index
---
docs/README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++
docs/_static/js/page.js | 2 +-
docs/_static/js/sidebar.js | 3 +-
docs/_static/mxnet.css | 18 ++++++++----
docs/index.md | 1 +
5 files changed, 85 insertions(+), 8 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index 35c6d3e..ad64b76 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,9 @@
# MXNet documentation
+## How to build MXNet website
+
+MXNet Documentation Website is built with [sphinx
1.5.1](http://www.sphinx-doc.org/en/1.5.1/intro.html).
+
A built version of document is available at http://mxnet.io
To build the documents locally, we need to first install
[docker](https://docker.com).
@@ -11,6 +15,12 @@ git clone --recursive
https://github.com/apache/incubator-mxnet.git mxnet
cd mxnet && make docs
```
+In case docker method is not available, there is an alternate method:
+```bash
+sudo pip install sphinx==1.5.1 CommonMark==0.5.4 breathe mock==1.0.1
recommonmark pypandoc
+cd mxnet/docs && make html USE_OPENMP=0
+```
+
The results will be available at `docs/_build/html/`.
Note:
@@ -20,3 +30,62 @@ Note:
- If C++ code fails to build, run `make clean`
- If CSS or javascript are changed, we often need to do a *force refresh* in
the
browser to clear the cache.
+- If search doesn't work, we need to `make clean` and rebuild.
+
+## File structure
+
+1. Static files such as css, javascript and html templates are under `_static`
folder:
+- Javascript files are under `_static/js` folder.
+- Layout templates and landing page html file are under `_static/mxnet-theme`
folder.
+- `_static/mxnet.css` contains all MXNet website styles.
+
+2. Sphinx converts markdowns files to html. Page contents are markdown files.
Each content folder
+contains an index file as landing page.
+
+3. There are some utility scripts to help building website, such as `mxdoc.py`
and `build_version_doc/`.
+They are used to manipulate website contents during building.
+
+## Production website building process
+
+[Apache Jenkins MXNet website building
job](https://builds.apache.org/job/incubator-mxnet-build-site/) is used to
build MXNet website.
+There are two ways to trigger this job.
+First is nightly build for master branch.
+Second is manually trigger job when a new version is released. This will build
for new version.
+
+The job will fetch mxnet repository, build MXNet website and push all static
files to [host repository](https://github.com/apache/incubator-mxnet-site.git).
+The host repo is hooked with [Apache
gitbox](https://gitbox.apache.org/repos/asf?p=incubator-mxnet-site.git;a=summary)
to host website.
+
+## Build versioning website
+
+`make docs` doesn't add any version information. Version information is added
by [Apache Jenkins MXNet website building
job](https://builds.apache.org/job/incubator-mxnet-build-site/).
+Landing page will point to the latest released version. Older versions and
master version are placed under versions folder.
+After completing website update and testing it locally, we also need to build
and test versioning website.
+
+Python Beautifulsoup is the dependency:
+
+```bash
+sudo pip install beautifulsoup4
+```
+
+The essenitial part of adding version is to use `AddPackageLink.py` to add
Apache source packages and
+`AddVersion.py` to update all version related information on website. These
two scripts are used in `build_doc.sh` and `build_all_version`.
+
+`build_doc.sh` is used by Apache Jenkins MXNet webiste building job to
incremental adding version. We don't need it
+for local website development.
+
+`build_all_version.sh` is to rebuild versioning website locally and is useful
to verify versioning website locally.
+We need to specify which versions to be built. This can be set in `tag_list`
variable at the beginning of the script.
+Version order should be from latest to oldest and placing master at the end.
We may also want to modify `mxnet_url`
+variable to our own repository for local testing. Another use case is to
completely rebuild website with specific versions.
+Although this will not happen often, we can use it to rebuld whole website and
push to [host repo](https://github.com/apache/incubator-mxnet-site.git).
+
+```bash
+./build_all_version.sh
+```
+
+## Develop notes
+
+1. `AddVersion.py` depends on Beautiful library, which requires target html
files to have close tags. Although open tag html can still be rendered by
browser, it will be problematic for Beautifulsoup.
+
+2. `AddVersion.py` and `AddPackageLink.py` manipulates contents for website.
If there are layout changes, it may break these two scripts. We need to change
scripts respectively.
+
diff --git a/docs/_static/js/page.js b/docs/_static/js/page.js
index befb5b0..08afea1 100644
--- a/docs/_static/js/page.js
+++ b/docs/_static/js/page.js
@@ -29,7 +29,7 @@ for (var i = 1; i < pathArr.length; ++i) {
lastUrl += '/' + pathArr[i];
if (pathArr[i].endsWith('.html')) pathArr[i] = pathArr[i].substring(0,
pathArr[i].length - 5);
if (i == pathArr.length - 1 || pathArr[i + 1].length == 0 ||
- pathArr[i + 1] == 'index.html') urlTracker += "<li><a
class='last-tracker' href=" + lastUrl + ">" + pathArr[i].replace(/_/g, ' ') +
"</a></li>";
+ pathArr[i + 1] == 'index.html') urlTracker += "<li>" +
pathArr[i].replace(/_/g, ' ') + "</li>";
else {
// Check whether current folder has index.html.
// If it doesn't, disable the link.
diff --git a/docs/_static/js/sidebar.js b/docs/_static/js/sidebar.js
index 86ef469..1c50cfd 100644
--- a/docs/_static/js/sidebar.js
+++ b/docs/_static/js/sidebar.js
@@ -54,7 +54,8 @@ function render_lefttoc() {
render_left_helper($($.parseHTML(data)).find('#table-of-contents > div > ul'));
}
else {
-
render_left_helper($($.parseHTML(data)).find('.leftsidebar >
.sphinxsidebarwrapper > ul.current > li.current > ul'));
+ var lastToc = $($.parseHTML(data)).find('.leftsidebar
> .sphinxsidebarwrapper > ul.current > li.current > ul')
+ render_left_helper(lastToc);
var tocLink = $('.leftsidebar .sphinxsidebarwrapper
.leaf a');
var staticLink = 'http';
tocLink.each(function () {
diff --git a/docs/_static/mxnet.css b/docs/_static/mxnet.css
index ea25de5..7ade268 100644
--- a/docs/_static/mxnet.css
+++ b/docs/_static/mxnet.css
@@ -1,19 +1,19 @@
/*-------------------- AmazonEmber font -----------------------------------*/
@font-face {
font-family: AmazonEmber;
- src:
url(https://raw.githubusercontent.com/kevinthesun/web-data/MoreResourcesForWeb/mxnet/font/AmazonEmber_Rg.ttf);
+ src:
url(https://raw.githubusercontent.com/dmlc/web-data/master/mxnet/font/AmazonEmber_Rg.ttf);
font-weight: normal;
}
@font-face {
font-family: AmazonEmber;
- src:
url(https://raw.githubusercontent.com/kevinthesun/web-data/MoreResourcesForWeb/mxnet/font/AmazonEmber_Bd.ttf);
+ src:
url(https://raw.githubusercontent.com/dmlc/web-data/master/mxnet/font/AmazonEmber_Bd.ttf);
font-weight: bold;
}
@font-face {
font-family: AmazonEmber;
- src:
url(https://raw.githubusercontent.com/kevinthesun/web-data/MoreResourcesForWeb/mxnet/font/AmazonEmber_Th.ttf);
+ src:
url(https://raw.githubusercontent.com/dmlc/web-data/master/mxnet/font/AmazonEmber_Th.ttf);
font-weight: 300;
}
@@ -374,6 +374,12 @@ div .burgerIcon a {
max-width: 250px;
}
+#plusMenu .dropdown-submenu>.dropdown-menu {
+ left: 138px;
+ top: 0;
+ background: #fff;
+}
+
#burgerMenu li, #plusMenu li {
height: 30px;
list-style-position: inside;
@@ -391,7 +397,7 @@ li.dropdown-submenu ul.dropdown-menu a {
padding-left: 20px !important;
}
-@media screen and (max-width: 360px) {
+@media screen and (max-width: 420px) {
li.dropdown-submenu ul.dropdown-menu a {
font-size: 12px !important;
}
@@ -404,7 +410,7 @@ li.dropdown-submenu ul.dropdown-menu a {
.dropdown-submenu>.dropdown-menu {
top: -8px;
- left: 200px;
+ left: 250px;
-webkit-border-radius: 0 6px 6px 6px;
-moz-border-radius: 0 6px 6px;
border-radius: 0 6px 6px 6px;
@@ -902,7 +908,7 @@ div.page-tracker a {
color: #337ab7;
}
-div.page-tracker a.last-tracker {
+div.page-tracker li:last-child {
color: #aab7b8;
}
diff --git a/docs/index.md b/docs/index.md
index 37d5887..582bd06 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -12,3 +12,4 @@ These are used to generate the indexes for search
functionality.
- [Get Started Documents](get_started/index.md)
- [System Documents](architecture/index.md)
- [Tutorials](tutorials/index.md)
+- [Community](community/index.md)
--
To stop receiving notification emails like this one, please contact
['"[email protected]" <[email protected]>'].
