diff --git a/.github/workflows/docs-multiversion.yml b/.github/workflows/docs-multiversion.yml new file mode 100644 index 00000000..57725be4 --- /dev/null +++ b/.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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..d654cb24 --- /dev/null +++ b/.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 diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb..25548584 100644 --- a/docs/Makefile +++ b/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/ diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 00000000..31a12578 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} diff --git a/docs/conf.py b/docs/conf.py index 6410fc76..6a28618a 100644 --- a/docs/conf.py +++ b/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", "") diff --git a/docs/requirements.txt b/docs/requirements.txt index fe0a46eb..ecbd3ac6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx==5.0.2 myst-parser==0.18.0 -sphinx-rtd-theme \ No newline at end of file +sphinx-rtd-theme +sphinx-multiversion==0.2.4