Add mike

.github/workflows/ci.yml

@@ -82,7 +82,7 @@ jobs:
 
     - name: install mkdocs-material-insiders
       if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')
-      run: pip install https://files.scolvin.com/${MKDOCS_TOKEN}/mkdocs-material/mkdocs_material-8.2.8+insiders.4.12.0-py3-none-any.whl
+      run: pip install https://files.scolvin.com/${MKDOCS_TOKEN}/mkdocs-material/mkdocs_material-9.1.5+insiders.4.32.4-py3-none-any.whl
       env:
         MKDOCS_TOKEN: ${{ secrets.mkdocs_token }}
 
@@ -107,9 +107,9 @@ jobs:
         with:
           jobs: ${{ toJSON(needs) }}
 
-  deploy:
+  publish_docs:
     needs: [check]
-    if: "success() && startsWith(github.ref, 'refs/tags/')"
+    if: "success() && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))"
     runs-on: ubuntu-latest
 
     steps:
@@ -120,35 +120,62 @@ jobs:
         with:
           python-version: '3.9'
 
-      - name: get docs
-        uses: actions/download-artifact@v3
+      - name: install
+        run: pip install -r requirements/docs.txt
+
+      - name: install mkdocs-material-insiders
+        run: pip install https://files.scolvin.com/${MKDOCS_TOKEN}/mkdocs-material/mkdocs_material-9.1.5+insiders.4.32.4-py3-none-any.whl
+        env:
+          MKDOCS_TOKEN: ${{ secrets.mkdocs_token }}
+
+      - name: Set git credentials
+        run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+          git config --global pull.rebase true
+          git pull origin docs-site
+
+      - run: mike deploy -b docs-site dev --push
+        if: github.ref == 'refs/heads/main'
+
+      - name: check version
+        if: "startsWith(github.ref, 'refs/tags/')"
+        id: check-version
+        uses: samuelcolvin/[email protected]
+        with:
+          version_file_path: 'dirty_equals/version.py'
+
+      - run: mike deploy -b docs-site ${{ steps.check-version.outputs.VERSION_MAJOR_MINOR }} --push
+        if: "startsWith(github.ref, 'refs/tags/') && !fromJSON(steps.check-version.outputs.IS_PRERELEASE)"
+
+  deploy:
+    needs: [check]
+    if: "success() && startsWith(github.ref, 'refs/tags/')"
+    runs-on: ubuntu-latest
+    environment: release
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: set up python
+        uses: actions/setup-python@v4
         with:
-          name: docs
-          path: site
+          python-version: '3.10'
 
       - name: install
-        run: pip install -U twine build packaging
+        run: pip install -U build
 
       - name: check version
         id: check-version
-        run: python <(curl -Ls https://gist.githubusercontent.com/samuelcolvin/4e1ad439c5489e8d6478cdee3eb952ef/raw/check_version.py)
-        env:
-          VERSION_PATH: 'dirty_equals/version.py'
+        uses: samuelcolvin/check-python[email protected]
+        with:
+          version_file_path: 'dirty_equals/version.py'
 
       - name: build
         run: python -m build
 
-      - run: twine check dist/*
-
-      - name: upload to pypi
-        run: twine upload dist/*
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.pypi_token }}
-
-      - name: publish docs
-        uses: JamesIves/github-pages-deploy-action@v4
-        if: '!fromJSON(steps.check-version.outputs.IS_PRERELEASE)'
-        with:
-          branch: gh-pages
-          folder: site
+      - name: Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docs/index.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="/img/logo-text.svg" alt="dirty-equals">
+  <img src="./img/logo-text.svg" alt="dirty-equals">
 </p>
 <p align="center">
   <em>Doing dirty (but extremely useful) things with equals.</em>

docs/plugins.py

@@ -15,23 +15,7 @@
 
 
 def on_pre_build(config: Config):
-    test_examples()
-
-
-def test_examples():
-    """
-    Run the examples tests.
-    """
-    try:
-        run_pytest = getattr('pytest', 'main')
-    except AttributeError:
-        logger.info('pytest not installed, skipping examples tests')
-    else:
-        logger.info('running examples tests...')
-        return_code = run_pytest(['-q', '-p', 'no:sugar', 'tests/test_docs.py'])
-        if return_code != 0:
-            logger.warning('examples tests failed')
-
+    pass
 
 def on_files(files: Files, config: Config) -> Files:
     return remove_files(files)
@@ -53,21 +37,13 @@ def remove_files(files: Files) -> Files:
 
 
 def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) -> str:
-    markdown = reinstate_code_titles(markdown)
     return add_version(markdown, page)
 
 
-def reinstate_code_titles(markdown: str) -> str:
-    """
-    Fix titles in code blocks, see https://youtrack.jetbrains.com/issue/PY-53246.
-    """
-    return re.sub(r'^(```py)\s*\ntitle=', r'\1 title=', markdown, flags=re.M)
-
-
 def add_version(markdown: str, page: Page) -> str:
-    if page.abs_url == '/':
+    if page.file.src_uri == 'index.md':
         version_ref = os.getenv('GITHUB_REF')
-        if version_ref:
+        if version_ref and version_ref.startswith('refs/tags/'):
             version = re.sub('^refs/tags/', '', version_ref.lower())
             version_str = f'Documentation for version: **{version}**'
         else:

mkdocs.yml

@@ -63,6 +63,8 @@ markdown_extensions:
       emoji_generator: !!python/name:materialx.emoji.to_svg
 
 extra:
+  version:
+    provider: mike
   analytics:
     provider: google
     property: G-FLP20728CW
@@ -76,6 +78,9 @@ watch:
   - dirty_equals
 
 plugins:
+  - mike:
+      alias_type: symlink
+      canonical_version: latest
   - search
   - mkdocstrings:
       handlers:

requirements/docs.in

@@ -1,4 +1,6 @@
 black
+# waiting for https://github.com/jimporter/mike/issues/154
+git+https://github.com/jimporter/mike.git
 mkdocs
 mkdocs-material
 mkdocs-simple-hooks

requirements/docs.txt

@@ -1,6 +1,6 @@
 #
-# This file is autogenerated by pip-compile with Python 3.10
-# by the following command:
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
 #
 #    pip-compile --output-file=requirements/docs.txt requirements/docs.in
 #
@@ -24,8 +24,13 @@ griffe==0.27.1
     # via mkdocstrings-python
 idna==3.4
     # via requests
+importlib-metadata==6.6.0
+    # via mike
+importlib-resources==5.12.0
+    # via mike
 jinja2==3.1.2
     # via
+    #   mike
     #   mkdocs
     #   mkdocs-material
     #   mkdocstrings
@@ -42,9 +47,12 @@ markupsafe==2.1.2
     #   mkdocstrings
 mergedeep==1.3.4
     # via mkdocs
+mike @ git+https://github.com/jimporter/mike.git
+    # via -r requirements/docs.in
 mkdocs==1.4.2
     # via
     #   -r requirements/docs.in
+    #   mike
     #   mkdocs-autorefs
     #   mkdocs-material
     #   mkdocs-simple-hooks
@@ -83,6 +91,7 @@ python-dateutil==2.8.2
     # via ghp-import
 pyyaml==6.0
     # via
+    #   mike
     #   mkdocs
     #   pymdown-extensions
     #   pyyaml-env-tag
@@ -98,5 +107,9 @@ tomli==2.0.1
     # via black
 urllib3==1.26.15
     # via requests
+verspec==0.1.0
+    # via mike
 watchdog==3.0.0
     # via mkdocs
+zipp==3.15.0
+    # via importlib-metadata