Gihhub actions for docs (mlc-ai#245)

This PR adds GH actions for docs

.github/workflows/documentation.yml

@@ -1,22 +1,39 @@
-name: Documentation
+name: Build Docs
+
 on:
   push:
     branches:
-    - main
-    paths:
-    - “docs/”
+      - main
+
 jobs:
-  build:
+  test_linux:
+    name: Deploy Docs
     runs-on: ubuntu-latest
+
     steps:
-    - uses: actions/setup-python@v2
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v2
       with:
-        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
-    - name: Build and Commit
-      uses: sphinx-notes/pages@v3
-    - name: Push changes
-      uses: ad-m/github-push-action@master
+        submodules: recursive
+
+    - name: Configuring build Environment
+      run: |
+        sudo apt-get update
+        python -m pip install -U pip wheel
+
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        branch: sphinx-gh-pages
+        ruby-version: '3.0'
+
+    - name: Installing dependencies
+      run: |
+        python -m pip install -r docs/requirements.txt
+        gem install jekyll jekyll-remote-theme
+
+    - name: Deploying on GitHub Pages
+      if: github.ref == 'refs/heads/main'
+      run: |
+        git remote set-url origin https://x-access-token:${{ secrets.MLC_GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+        git config --global user.email "mlc-gh-actions-bot@nomail"
+        git config --global user.name "mlc-gh-actions-bot"
+        ./scripts/gh_deploy_site.sh

CONTRIBUTORS.md

@@ -0,0 +1,6 @@
+MLC LLM Contributors
+====================
+
+
+## List of Contributors
+- [Full List of Contributors](https://github.com/mlc-ai/mlc-llm/graphs/contributors)

docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= python -m sphinx
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/contribute/community.rst

@@ -7,17 +7,24 @@ MLC-LLM Community Guidelines
   :depth: 2
   :local:
 
-Welcome to the MLC-LLM community! Just like you, all of us are in awe of the immense power of large language models. Our goal for MLC-LLM is to foster a project that is driven by an open-source community, working together to democratize this technology and make it accessible across various devices. We are thrilled to have you as part of our community and eagerly anticipate your valuable contributions.
+Welcome to the MLC-LLM community! Just like you, all of us are in awe of the immense power of large language models.
+Our goal for MLC-LLM is to foster a project that is driven by an open-source community, working together to democratize
+this technology and make it accessible across various devices. We are thrilled to have you as part of our
+community and eagerly anticipate your valuable contributions.
 
 
 .. _community_discussion:
 
 Participate in Community Discussions
 ------------------------------------
 
-We encourage open discussions. If you encounter a bug or have a feature request, please file an issue in MLC-LLM's GitHub `issue tracker <https://github.com/mlc-ai/mlc-llm/issues>`__. You are encouraged to tag the issue with labels such as "bug," "feature request," or "iOS" so that the relevant developers can quickly notice your concern.
+We encourage open discussions. If you encounter a bug or have a feature request, please file an issue in MLC-LLM's
+GitHub `issue tracker <https://github.com/mlc-ai/mlc-llm/issues>`__. You are encouraged to tag the issue with labels
+such as "bug," "feature request," or "iOS" so that the relevant developers can quickly notice your concern.
 
-Additionally, we have set up a `discord server <https://discord.gg/9Xpy2HGBuD>`__ for online discussions. While we encourage participation in the Discord server, we also recommend creating a GitHub issue even if the topic has been discussed there. This ensures that the discussion is archived and searchable for future reference.
+Additionally, we have set up a `discord server <https://discord.gg/9Xpy2HGBuD>`__ for online discussions.
+While we encourage participation in the Discord server, we also recommend creating a GitHub issue even if the
+topic has been discussed there. This ensures that the discussion is archived and searchable for future reference.
 
 Before submitting an issue, we kindly ask you to check our `FAQ page :doc:/misc/` to see if your question has already been answered.
 
@@ -31,11 +38,15 @@ Contribute to MLC-LLM
 Fork and Create Pull Requests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Ready to contribute to MLC-LLM? Awesome! We are excited to see you are ready to contribute your code. The standard way to make changes to MLC-LLM code base is through creating a `pull-request <https://github.com/mlc-ai/mlc-llm/pulls>`__, and we will review your code and merge it to the code base when it is ready.
+Ready to contribute to MLC-LLM? Awesome! We are excited to see you are ready to contribute your code.
+The standard way to make changes to MLC-LLM code base is through creating a `pull-request <https://github.com/mlc-ai/mlc-llm/pulls>`__,
+and we will review your code and merge it to the code base when it is ready.
 
-The first step to become a developer is to `fork <https://github.com/mlc-ai/mlc-llm/fork>`__ the repository to your own github account, you will notice a repository under ``https://github.com/username/mlc-llm`` where ``username`` is your github user name.
+The first step to become a developer is to `fork <https://github.com/mlc-ai/mlc-llm/fork>`__ the repository to your own
+github account, you will notice a repository under ``https://github.com/username/mlc-llm`` where ``username`` is your github user name.
 
-You can clone your fork to your local machine and commit changes, or edit the contents of your fork (in the case you are just fixing typos) on github directly. Once your update is complete, you can click the ``contribute`` button and open a pull request to the main repository.
+You can clone your fork to your local machine and commit changes, or edit the contents of your fork (in the case you are just fixing typos)
+on github directly. Once your update is complete, you can click the ``contribute`` button and open a pull request to the main repository.
 
 .. _contribute-new-models:
 
@@ -44,51 +55,77 @@ Contribute New Models to MLC-LLM
 
 Woohoo! Congratulations
 
-* If you compiled a model for existing model architecture by following our :doc:`../tutorials/compile-models` tutorial. Please upload your model stored in ``dist`` directory to Hugging Face (an example can be found `here <https://huggingface.co/mlc-ai/mlc-chat-vicuna-v1-7b-q4f32_0/tree/main>`__), and please create a pull request to MLC-LLM and add your model code to the `model zoo <https://github.com/mlc-ai/mlc-llm/tree/main/docs/model-zoo.rst>`__, and create a issue to track the speed and memory consumption of your model, see an example `here <https://github.com/mlc-ai/mlc-llm/issues/15>`__ (you don't need to test on all devices, let the community build it together!).
-* If you add a new model variant to MLC-LLM by following our :doc:`../tutorials/bring-your-own-models` tutorial. Please create a pull request to add your model architecture (currently model architectures are placed under `relax_models <https://github.com/mlc-ai/mlc-llm/tree/main/mlc_llm/relax_model>`__ folder).
+* If you compiled a model for existing model architecture by following our :doc:`../tutorials/compile-models` tutorial.
+  Please upload your model stored in ``dist`` directory to Hugging Face (an example can be
+  found `here <https://huggingface.co/mlc-ai/mlc-chat-vicuna-v1-7b-q4f32_0/tree/main>`__), and please create a
+  pull request to MLC-LLM and add your model code to the `model zoo <https://github.com/mlc-ai/mlc-llm/tree/main/docs/model-zoo.rst>`__,
+  and create a issue to track the speed and memory consumption of your model, see an example `here <https://github.com/mlc-ai/mlc-llm/issues/15>`__
+  (you don't need to test on all devices, let the community build it together!).
+* If you add a new model variant to MLC-LLM by following our :doc:`../tutorials/bring-your-own-models` tutorial.
+  Please create a pull request to add your model architecture (currently model architectures are placed under
+  `relax_models <https://github.com/mlc-ai/mlc-llm/tree/main/mlc_llm/relax_model>`__ folder).
 
 .. _coding-styles:
 
 Coding Styles
 ^^^^^^^^^^^^^
 
-For python codes, we generally follow the `PEP8 style guide <https://peps.python.org/pep-0008/>`__. The python comments follow `NumPy style <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`__ python docstrings. To make things easy, you can use `black <https://pypi.org/project/black/>`__ to automatically format your python code.
+For python codes, we generally follow the `PEP8 style guide <https://peps.python.org/pep-0008/>`__.
+The python comments follow `NumPy style <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`__ python docstrings.
+To make things easy, you can use `black <https://pypi.org/project/black/>`__ to automatically format your python code.
 
 .. code:: bash
-  
+
       pip install black
       black your_python_file.py
 
-For C++ codes, we generally follow the `Google C++ style guide <https://google.github.io/styleguide/cppguide.html>`__. The C++ comments should be `Doxygen compatible <http://www.doxygen.nl/manual/docblocks.html#cppblock>`__. Fo your convenience, you can use `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__ to automatically format your C++ code.
+For C++ codes, we generally follow the `Google C++ style guide <https://google.github.io/styleguide/cppguide.html>`__.
+The C++ comments should be `Doxygen compatible <http://www.doxygen.nl/manual/docblocks.html#cppblock>`__.
+Fo your convenience, you can use `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__ to automatically format your C++ code.
 
 .. code:: bash
-  
+
       clang-format -i your_cpp_file.cpp
 
 .. _general-development-process:
 
 General Development Process
 ---------------------------
 
-Everyone in the community is welcomed to send patches, documents, and propose new directions to the project. The key guideline here is to enable everyone in the community to get involved and participate the decision and development.  When major changes are proposed, an RFC (Request for Comments) should be sent to allow discussion by the community. We encourage public discussion, archivable channels such as github issues, so that everyone in the community can participate and review the process later.
+Everyone in the community is welcomed to send patches, documents, and propose new directions to the project.
+The key guideline here is to enable everyone in the community to get involved and participate the decision and development.
+We encourage public discussion in different channels, so that everyone in the community can participate
+and get informed in developments.
 
-Code reviews are one of the key ways to ensure the quality of the code. High-quality code reviews prevent technical debt for long-term and are crucial to the success of the project. A pull request needs to be reviewed before it gets merged. A committer who has the expertise of the corresponding area would moderate the pull request and the merge the code when it is ready. The corresponding committer could request multiple reviewers who are familiar with the area of the code. We encourage contributors to request code reviews themselves and help review each other's code -- remember everyone is volunteering their time to the community, high-quality code review itself costs as much as the actual code contribution, you could get your code quickly reviewed if you do others the same favor.
+Code reviews are one of the key ways to ensure the quality of the code. High-quality code reviews prevent technical debt
+for long-term and are crucial to the success of the project. A pull request needs to be reviewed before it gets merged.
+A committer who has the expertise of the corresponding area would moderate the pull request and the merge the code when
+it is ready. The corresponding committer could request multiple reviewers who are familiar with the area of the code.
+We encourage contributors to request code reviews themselves and help review each other's code -- remember everyone
+is volunteering their time to the community, high-quality code review itself costs as much as the actual code
+contribution, you could get your code quickly reviewed if you do others the same favor.
 
-The community should strive to reach a consensus on technical decisions through discussion. We expect committers to moderate technical discussions in a diplomatic way, and provide suggestions with clear technical reasoning when necessary.
+The community should strive to reach a consensus on technical decisions through discussion. We expect committers to
+moderate technical discussions in a diplomatic way, and provide suggestions with clear technical reasoning when necessary.
 
 
 .. _roles-committers:
 
 Committers
 ^^^^^^^^^^
 
-Committers are individuals who are granted the write access to the project. A committer is usually responsible for a certain area or several areas of the code where they oversee the code review process.
+Committers are individuals who are granted the write access to the project. A committer is usually responsible for
+a certain area or several areas of the code where they oversee the code review process.
 The area of contribution can take all forms, including code contributions and code reviews, documents, education, and outreach.
 The review of pull requests will be assigned to the committers who recently contribute to the area this PR belong to.
-Committers are essential for a high quality and healthy project. The community actively look for new committers from contributors. Each existing committer can nominate new committers to MLC-LLM.
+Committers are essential for a high quality and healthy project. The community actively look for new committers
+from contributors. Each existing committer can nominate new committers to MLC projects.
 
 .. _roles-contributors:
 
 Contributors
 ^^^^^^^^^^^^
-We also welcome contributors if you are not ready to be a committer yet. Everyone who contributes to the project (in the form of code, bugfix, documentation, tutorials, etc) is a contributors. We maintain a `page <https://github.com/mlc-ai/mlc-llm/blob/master/CONTRIBUTORS.md>`__ to acknowledge contributors, please let us know if you contribute to the project and your name is not included in the list.
+We also welcome contributors if you are not ready to be a committer yet. Everyone who contributes to
+the project (in the form of code, bugfix, documentation, tutorials, etc) is a contributors.
+We maintain a `page <https://github.com/mlc-ai/mlc-llm/blob/main/CONTRIBUTORS.md>`__ to acknowledge contributors,
+please let us know if you contribute to the project and your name is not included in the list.

docs/requirements.txt

@@ -1,4 +1,4 @@
 sphinx-tabs == 3.4.1
-sphinx-gallery == 5.2.3
-sphinx-rtd-theme == 1.1.1
+sphinx-rtd-theme
+sphinx == 5.2.3
 sphinx-toolbox == 3.4.0

scripts/build_site.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -euxo pipefail
+
+cd docs && make html && cd ..
+
+cd site && jekyll b && cd ..
+
+rm -rf site/_site/docs
+cp -r docs/_build/html site/_site/docs

scripts/gh_deploy_site.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# NOTE: this script is triggered by github action automatically
+# when megred into main
+
+set -euxo pipefail
+
+scripts/build_site.sh
+
+git fetch
+git checkout -B gh-pages origin/gh-pages
+rm -rf docs .gitignore
+mkdir -p docs
+cp -rf site/_site/* docs
+touch docs/.nojekyll
+
+DATE=`date`
+git add docs && git commit -am "Build at ${DATE}"
+git push origin gh-pages
+git checkout main && git submodule update
+echo "Finish deployment at ${DATE}"

scripts/local_deploy_site.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# NOTE: use this script to check local site
+
+set -euxo pipefail
+
+scripts/build_site.sh
+
+cd site && jekyll serve  --skip-initial-build --host localhost --baseurl /mlc-llm --port 8888

site/_config.yml

@@ -37,5 +37,7 @@ course_title:
 navigation:
   - title: Home
     link: /
+  - title: Docs
+    link: /docs
   - title: Github
     link: https://github.com/mlc-ai/mlc-llm