ci(docs): Build docs when push/PR to master and release version. (#935)

Signed-off-by: longjin <longjin@DragonOS.org>

.github/workflows/docs-multiversion.yml

@@ -0,0 +1,36 @@
+name: Build multiversion docs
+
+on:
+  push:
+    branches: [ "master" ]
+    tags: [ "v*", "V*"]
+
+env:
+    GITHUB_REPOSITORY: ${{ github.repository }}
+    GITHUB_REF: ${{ github.ref }}
+
+jobs:
+
+  build-multiversion:
+    if: github.repository == 'DragonOS-Community/DragonOS'
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        ref: master
+      
+    - name: install requirements
+      working-directory: ./docs
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y python3-pip
+        pip3 install -r requirements.txt
+
+    - name: build docs
+      working-directory: ./docs
+      shell: bash -ileo pipefail {0}
+
+      run: |
+        make html-multiversion

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Build current version docs
+
+on:
+  pull_request:
+    branches: [ "master" ]
+    # paths:
+    #   - 'docs/**'
+
+env:
+    GITHUB_REPOSITORY: ${{ github.repository }}
+    GITHUB_REF: ${{ github.ref }}
+
+jobs:
+
+  build-current-version:
+    if: github.repository == 'DragonOS-Community/DragonOS'
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      
+    - name: install requirements
+      working-directory: ./docs
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y python3-pip
+        pip3 install -r requirements.txt
+
+    - name: build docs
+      working-directory: ./docs
+      shell: bash -ileo pipefail {0}
+
+      run: |
+        make html

docs/Makefile

@@ -18,3 +18,7 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY:
+html-multiversion:
+	rm -rf ./$(BUILDDIR) && sphinx-multiversion "$(SOURCEDIR)" ./$(BUILDDIR)/html && cp -rf ./$(BUILDDIR)/html/master/* ./$(BUILDDIR)/html/

docs/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

docs/conf.py

@@ -29,7 +29,7 @@ release = 'dev'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['myst_parser']
+extensions = ['myst_parser', 'sphinx_multiversion']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -59,6 +59,12 @@ html_theme = 'sphinx_rtd_theme'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_sidebars = {
+    '**': [
+        'versioning.html',
+    ],
+}
+
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",
@@ -74,6 +80,11 @@ myst_enable_extensions = [
     "tasklist",
 ]
 
+# sphinx-multiversion 指定哪个分支为 lastest 版本
+smv_latest_version = 'master'
+smv_released_pattern = r'^tags/.*$'           # Tags only
+smv_tag_whitelist = r'^(V.*|v.*)$'
+smv_branch_whitelist = "master"
 
 # Define the canonical URL if you are using a custom domain on Read the Docs
 html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx==5.0.2
 myst-parser==0.18.0
-sphinx-rtd-theme
+sphinx-rtd-theme
+sphinx-multiversion==0.2.4