docs: switch to new Lit template (#2097)

.devcontainer/Dockerfile

@@ -6,12 +6,21 @@ FROM mcr.microsoft.com/vscode/devcontainers/python:${VARIANT}
 
 # [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
 ARG NODE_VERSION="none"
-RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+RUN if [ "${NODE_VERSION}" != "none" ]; then \
+      su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; \
+    fi
 
 COPY requirements/ /tmp/pip-tmp/requirements/
 COPY requirements.txt /tmp/pip-tmp/
-RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements/devel.txt -r /tmp/pip-tmp/requirements/docs.txt \
-    && rm -rf /tmp/pip-tmp
+RUN \
+    pip3 install awscli && \
+    aws s3 sync --no-sign-request s3://sphinx-packages/ dist/  && \
+    pip3 --disable-pip-version-check --no-cache-dir install \
+      -r /tmp/pip-tmp/requirements/devel.txt \
+      -r /tmp/pip-tmp/requirements/docs.txt \
+      --find-links="https://download.pytorch.org/whl/cpu/torch_stable.html" \
+      --find-links="dist/" && \
+    rm -rf /tmp/pip-tmp
 
 # [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
 # COPY requirements.txt /tmp/pip-tmp/

.github/workflows/docs-build.yml

@@ -21,6 +21,8 @@ env:
   PYPI_CACHE: "_ci-cache_PyPI"
   PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: "python"
   TOKENIZERS_PARALLELISM: false
+  SPHINX_MOCK_REQUIREMENTS: 0
+  SPHINX_FETCH_ASSETS: 0
 
 jobs:
   docs-make:
@@ -30,8 +32,6 @@ jobs:
       fail-fast: false
       matrix:
         check: [html, doctest, linkcheck]
-    env:
-      SPHINX_MOCK_REQUIREMENTS: 0
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v3
@@ -50,24 +50,26 @@ jobs:
         if: ${{ matrix.check == 'html' }}
         # install Texlive, see https://linuxconfig.org/how-to-install-latex-on-ubuntu-20-04-focal-fossa-linux
         run: |
-          sudo apt-get update
+          sudo apt-get update --fix-missing
           sudo apt-get install -y \
             texlive-latex-extra texlive-pictures texlive-fonts-recommended dvipng cm-super
 
+      - name: Pull sphinx template
+        run: |
+          pip install awscli
+          aws s3 sync --no-sign-request s3://sphinx-packages/ dist/
       - name: Install package & dependencies
         run: |
           sudo apt-get update --fix-missing
           sudo apt-get install -y cmake
           pip --version
           pip install . -U -r requirements/docs.txt \
-            --find-links=${PYPI_CACHE} --find-links=${TORCH_URL}
+            --find-links="${PYPI_CACHE}" --find-links="${TORCH_URL}" --find-links="dist/"
           pip list
 
       - name: Test Examples in Documentation
         if: ${{ matrix.check == 'doctest' }}
         working-directory: ./docs
-        env:
-          SPHINX_FETCH_ASSETS: 0
         run: |
           make doctest
           make coverage
@@ -76,14 +78,15 @@ jobs:
         if: ${{ matrix.check == 'linkcheck' }}
         working-directory: ./docs
         env:
-          SPHINX_FETCH_ASSETS: 0
+          SPHINX_MOCK_REQUIREMENTS: 1
         run: make --jobs $(nproc) linkcheck SPHINXOPTS="--keep-going"
 
+      - name: Full build for deployment
+        if: github.event_name == 'push'
+        run: echo "SPHINX_FETCH_ASSETS=1" >> $GITHUB_ENV
       - name: Make Documentation
         if: ${{ matrix.check == 'html' }}
         working-directory: ./docs
-        env:
-          SPHINX_FETCH_ASSETS: 1
         run: make html --debug SPHINXOPTS="-W --keep-going"
 
       - name: Upload built docs

.readthedocs.yml

@@ -1,3 +1,17 @@
+# Copyright The Lightning AI team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # .readthedocs.yml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
@@ -6,23 +20,23 @@
 version: 2
 
 # Build documentation in the docs/ directory with Sphinx
+# reference: https://docs.readthedocs.io/en/stable/config-file/v2.html#sphinx
 sphinx:
-  configuration: docs/source/conf.py
   fail_on_warning: true
 
-# Optionally build your docs in additional formats such as PDF and ePub
-formats:
-  - htmlzip
-  # - pdf  # building both takes too log :(
-
 build:
   os: "ubuntu-22.04"
   tools:
     python: "3.9"
-
-# Optionally set the version of Python and requirements required to build your docs
-python:
-  install:
-    - requirements: requirements/docs.txt
-    - method: pip
-      path: .
+  commands:
+    - printenv
+    - pwd ; ls -lh
+    - pip install -U pip awscli --user
+    - python -m awscli s3 sync --no-sign-request s3://sphinx-packages/ dist/ ; ls -lh dist/
+    - >
+      pip install -e . -q -r requirements/docs.txt \
+          -f 'https://download.pytorch.org/whl/cpu/torch_stable.html' -f dist/ ;
+      pip list
+    # this need to be split so `sphinx-build` is picked from previous installation
+    - bash docs/rtfd-build.sh
+    - mkdir -p _readthedocs ; mv docs/build/html _readthedocs/html

docs/rtfd-build.sh

@@ -0,0 +1,12 @@
+# building for PRs and skip stable and latest states
+
+if ! [ $READTHEDOCS_VERSION == "latest" -o $READTHEDOCS_VERSION == "stable" ];
+then
+    cd ./docs ;
+    export SPHINX_FETCH_ASSETS=0 ;
+    make html --jobs $(nproc) ;
+    ls -lh build
+else
+    echo "Void build... :-]" ;
+    mkdir -p ./docs/build/html
+fi

docs/source/conf.py

@@ -17,7 +17,7 @@
 import shutil
 import sys
 
-import pt_lightning_sphinx_theme
+import lai_sphinx_theme
 from lightning_utilities.docs import fetch_external_assets
 from lightning_utilities.docs.formatting import _transform_changelog
 
@@ -30,7 +30,7 @@
 
 FOLDER_GENERATED = "generated"
 SPHINX_MOCK_REQUIREMENTS = int(os.environ.get("SPHINX_MOCK_REQUIREMENTS", True))
-SPHINX_FETCH_ASSETS = int(os.environ.get("SPHINX_FETCH_ASSETS", True))
+SPHINX_FETCH_ASSETS = int(os.environ.get("SPHINX_FETCH_ASSETS", False))
 
 html_favicon = "_static/images/icon.svg"
 
@@ -112,7 +112,7 @@ def _set_root_image_path(page_path: str):
     "sphinx_autodoc_typehints",
     "sphinx_paramlinks",
     "sphinx.ext.githubpages",
-    "pt_lightning_sphinx_theme.extensions.lightning",
+    "lai_sphinx_theme.extensions.lightning",
     "matplotlib.sphinxext.plot_directive",
 ]
 
@@ -168,8 +168,8 @@ def _set_root_image_path(page_path: str):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = "pt_lightning_sphinx_theme"
-html_theme_path = [pt_lightning_sphinx_theme.get_html_theme_path()]
+html_theme = "lai_sphinx_theme"
+html_theme_path = [lai_sphinx_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

requirements/docs.txt

@@ -5,7 +5,7 @@ pandoc ==2.3
 docutils ==0.19
 sphinxcontrib-fulltoc >=1.0
 sphinxcontrib-mockautodoc
-pt-lightning-sphinx-theme @ https://github.com/Lightning-AI/lightning_sphinx_theme/archive/master.zip
+lai-sphinx-theme  # need to be downloaded from s3://sphinx-packages/
 sphinx-autodoc-typehints ==1.23.0
 sphinx-paramlinks ==0.5.4
 sphinx-togglebutton ==0.3.2