renaming docs, adding dockerfile, github action (#185)

* renaming docs, adding dockerfile, github action * Update .github/workflows/gh_pages.yml Co-authored-by: Jiwon Gim <[email protected]> * action triggers --------- Co-authored-by: Jiwon Gim <[email protected]>
NCAR · Aug 15, 2024 · d457bbd · d457bbd
1 parent 5615094
commit d457bbd
Show file tree

Hide file tree

Showing 20 changed files with 161 additions and 2 deletions.
diff --git a/.github/workflows/gh_pages.yml b/.github/workflows/gh_pages.yml
@@ -0,0 +1,132 @@
+# Build and deploy documentation to GitHub Pages
+name: GitHub Pages
+
+on: 
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+env:
+  DEFAULT_BRANCH: "release"
+
+jobs:
+  build-and-deploy:
+    name: Build and deploy to gh-pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Debugging information
+        run: |
+          echo "github.ref:" ${{github.ref}}
+          echo "github.event_name:" ${{github.event_name}}
+          echo "github.head_ref:" ${{github.head_ref}}
+          echo "github.base_ref:" ${{github.base_ref}}
+          set -x
+          git rev-parse --abbrev-ref HEAD
+          git branch
+          git branch -a
+          git remote -v
+          python -V
+          pip list --not-required
+          pip list
+
+      # Clone and set up the old gh-pages branch
+      - name: Clone old gh-pages
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          set -x
+          git fetch
+          ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
+          rm -rf _gh-pages/.git/
+          mkdir -p _gh-pages/branch/
+
+      # If a push and default branch, copy build to _gh-pages/ as the "main"
+      # deployment.
+      - name: Build and copy documentation (default branch)
+        if: |
+          contains(github.event_name, 'push') &&
+          contains(github.ref, env.DEFAULT_BRANCH)
+        run: |
+          set -x
+          mkdir -p _build/html/versions
+
+          # create two copies of the documentation
+          # 1. the frozen version, represented as vX.X in the version switcher
+          docker build -t music_box -f docker/Dockerfile.docs .
+          id=$(docker create music_box)
+          docker cp $id:/build/docs/build/html tmpdocs
+          docker rm -v $id
+          version=$(sed -nr "s/^release = f'v(.+)\{suffix\}'.*$/\1/p" docs/source/conf.py)
+          mv tmpdocs _build/html/versions/${version}
+
+          # 2. stable, represented as vX.X (stable) in the version switcher
+          # edit conf.py to produce a version string that looks like vX.X (stable)
+          docker build -t music_box -f docker/Dockerfile.docs --build-arg SUFFIX=" (stable)" .
+          id=$(docker create music_box)
+          docker cp $id:/build/docs/build/html tmpdocs
+          docker rm -v $id
+          mv tmpdocs _build/html/versions/stable
+          # Delete everything under _gh-pages/ that is from the
+          # primary branch deployment.  Excludes the other branches
+          # _gh-pages/branch-* paths, and not including
+          # _gh-pages itself.
+          find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' ! -path '_gh-pages/versions*' -delete
+          rsync -a _build/html/versions/stable/* _gh-pages/
+          mkdir -p _gh-pages/versions
+          rsync -a _build/html/versions/* _gh-pages/versions
+          # mv docs/switcher.json _gh-pages
+
+      # If a push and not on default branch, then copy the build to
+      # _gh-pages/branch/$brname (transforming '/' into '--')
+      - name: Build and copy documentation (branch)
+        if: |
+          contains(github.event_name, 'push') &&
+          !contains(github.ref, env.DEFAULT_BRANCH)
+        run: |
+          set -x
+          docker build -t music_box -f docker/Dockerfile.docs .
+          id=$(docker create music_box)
+          docker cp $id:/music-box/docs/build/html tmpdocs
+          docker rm -v $id
+          brname="${{github.ref}}"
+          brname="${brname##refs/heads/}"
+          brdir=${brname//\//--}   # replace '/' with '--'
+          rm -rf   _gh-pages/branch/${brdir}
+          rsync -a tmpdocs/ _gh-pages/branch/${brdir}
+
+      # Go through each branch in _gh-pages/branch/, if it's not a
+      # ref, then delete it.
+      - name: Delete old feature branches
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          set -x
+          for brdir in `ls _gh-pages/branch/` ; do
+              brname=${brdir//--/\/}   # replace '--' with '/'
+              if ! git show-ref remotes/origin/$brname ; then
+                  echo "Removing $brdir"
+                  rm -r _gh-pages/branch/$brdir/
+              fi
+          done
+
+      # Add the .nojekyll file
+      - name: nojekyll
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          touch _gh-pages/.nojekyll
+
+      # Deploy
+      # https://github.com/peaceiris/actions-gh-pages
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _gh-pages/
+          force_orphan: true
diff --git a/docker/Dockerfile.docs b/docker/Dockerfile.docs
@@ -0,0 +1,24 @@
+FROM fedora:37
+
+RUN dnf -y update \
+    && dnf -y install \
+        git \
+        make \
+        python3 \
+        python3-pip \
+    && dnf clean all
+
+COPY . /music-box/
+
+WORKDIR /music-box
+
+RUN pip3 install -e .
+
+ARG SUFFIX=""
+ENV SWITCHER_SUFFIX=$SUFFIX
+
+RUN echo "The suffix is '$SWITCHER_SUFFIX'"
+
+RUN cd docs \
+    && pip install -r requirements.txt \
+    && make html
diff --git a/doc/Makefile → docs/Makefile b/doc/Makefile → docs/Makefile
diff --git a/doc/make.bat → docs/make.bat b/doc/make.bat → docs/make.bat
diff --git a/doc/requirements.txt → docs/requirements.txt b/doc/requirements.txt → docs/requirements.txt
diff --git a/doc/source/_static/MusicBox.svg → docs/source/_static/MusicBox.svg b/doc/source/_static/MusicBox.svg → docs/source/_static/MusicBox.svg
diff --git a/doc/source/_static/custom.css → docs/source/_static/custom.css b/doc/source/_static/custom.css → docs/source/_static/custom.css
diff --git a/doc/source/_static/favicon.png → docs/source/_static/favicon.png b/doc/source/_static/favicon.png → docs/source/_static/favicon.png
diff --git a/doc/source/_static/index_api.svg → docs/source/_static/index_api.svg b/doc/source/_static/index_api.svg → docs/source/_static/index_api.svg
diff --git a/doc/source/_static/index_contribute.svg → docs/source/_static/index_contribute.svg b/doc/source/_static/index_contribute.svg → docs/source/_static/index_contribute.svg
diff --git a/doc/source/_static/index_getting_started.svg → .../source/_static/index_getting_started.svg b/doc/source/_static/index_getting_started.svg → .../source/_static/index_getting_started.svg
diff --git a/doc/source/_static/index_user_guide.svg → docs/source/_static/index_user_guide.svg b/doc/source/_static/index_user_guide.svg → docs/source/_static/index_user_guide.svg
diff --git a/doc/source/_static/switcher.json → docs/source/_static/switcher.json b/doc/source/_static/switcher.json → docs/source/_static/switcher.json
diff --git a/doc/source/api/acom_music_box.rst → docs/source/api/acom_music_box.rst b/doc/source/api/acom_music_box.rst → docs/source/api/acom_music_box.rst
diff --git a/doc/source/api/index.rst → docs/source/api/index.rst b/doc/source/api/index.rst → docs/source/api/index.rst
diff --git a/doc/source/conf.py → docs/source/conf.py b/doc/source/conf.py → docs/source/conf.py
@@ -12,11 +12,14 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-release = acom_music_box.__version__
-project = f'Music Box ({release})'
+version = acom_music_box.__version__
+project = f'Music Box ({version})'
 copyright = f'2024-{datetime.datetime.now().year}, NCAR/UCAR'
 author = 'NCAR/UCAR'
 
+suffix = os.getenv("SWITCHER_SUFFIX", "")
+release = f'{version}{suffix}'
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 

diff --git a/doc/source/contributing/index.rst → docs/source/contributing/index.rst b/doc/source/contributing/index.rst → docs/source/contributing/index.rst
diff --git a/doc/source/getting_started.rst → docs/source/getting_started.rst b/doc/source/getting_started.rst → docs/source/getting_started.rst
diff --git a/doc/source/index.rst → docs/source/index.rst b/doc/source/index.rst → docs/source/index.rst
diff --git a/doc/source/user_guide/index.rst → docs/source/user_guide/index.rst b/doc/source/user_guide/index.rst → docs/source/user_guide/index.rst