From 403bec9c0516defdfc4509a5fcbfde44dbe8e633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:23:42 +0200 Subject: [PATCH 1/8] Update mkdocs and configure docs versioning --- .github/workflows/documentation.yml | 38 ++++++++--------- .../authentication/strategies/database.md | 4 +- docs/configuration/full-example.md | 42 +++++++++---------- docs/configuration/oauth.md | 42 +++++++++---------- mkdocs.yml | 37 ++++++++++------ pyproject.toml | 1 + 6 files changed, 89 insertions(+), 75 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 74332a58..9dbcc2b8 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -7,25 +7,25 @@ on: jobs: build: - runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: Set up Python 3.7 - uses: actions/setup-python@v1 - with: - python-version: 3.7 - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install flit - flit install --deps develop --extras oauth,redis - - name: Build - run: mkdocs build - - name: Deploy - uses: peaceiris/actions-gh-pages@v2.5.0 - env: - ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }} - PUBLISH_BRANCH: gh-pages - PUBLISH_DIR: ./site + - uses: actions/checkout@v3 + - name: Set up Python 3.7 + uses: actions/setup-python@v3 + with: + python-version: 3.7 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install flit + flit install --deps develop --extras oauth,redis + - name: Build + run: mkdocs build + - name: Get tag + run: | + python -c "from packaging import version; from fastapi_users import __version__; version = version.parse(__version__); print(f'DOCS_VERSION={version.major}.{version.minor}')" >> $GITHUB_ENV + - name: Deploy + run: | + git fetch origin gh-pages --depth=1 + mike deploy --push --update-aliases ${{ env.DOCS_VERSION }} latest diff --git a/docs/configuration/authentication/strategies/database.md b/docs/configuration/authentication/strategies/database.md index 2aa8cf34..58bd5972 100644 --- a/docs/configuration/authentication/strategies/database.md +++ b/docs/configuration/authentication/strategies/database.md @@ -37,12 +37,12 @@ It is structured like this: With Tortoise ORM, you need to define a proper Tortoise model for `AccessToken` and manually specify the user foreign key. Besides, you need to modify the Pydantic model a bit so that it works well with this Tortoise model. - === ":octicons-file-code-16: model.py" + === "model.py" ```py hl_lines="2 4 31-38" --8<-- "docs/src/db_tortoise_access_tokens_model.py" ``` - === ":octicons-file-code-16: adapter.py" + === "adapter.py" ```py hl_lines="2 4 13-14" --8<-- "docs/src/db_tortoise_access_tokens_adapter.py" ``` diff --git a/docs/configuration/full-example.md b/docs/configuration/full-example.md index f08beecf..a5cb56b6 100644 --- a/docs/configuration/full-example.md +++ b/docs/configuration/full-example.md @@ -8,39 +8,39 @@ Here is a full working example with JWT authentication to help get you started. ## SQLAlchemy -[Open :octicons-link-external-16:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/sqlalchemy) +[Open :material-open-in-new:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/sqlalchemy) -=== ":octicons-file-code-16: requirements.txt" +=== "requirements.txt" ``` --8<-- "examples/sqlalchemy/requirements.txt" ``` -=== ":octicons-file-code-16: main.py" +=== "main.py" ```py --8<-- "examples/sqlalchemy/main.py" ``` -=== ":octicons-file-code-16: app/app.py" +=== "app/app.py" ```py --8<-- "examples/sqlalchemy/app/app.py" ``` -=== ":octicons-file-code-16: app/db.py" +=== "app/db.py" ```py --8<-- "examples/sqlalchemy/app/db.py" ``` -=== ":octicons-file-code-16: app/models.py" +=== "app/models.py" ```py --8<-- "examples/sqlalchemy/app/models.py" ``` -=== ":octicons-file-code-16: app/users.py" +=== "app/users.py" ```py --8<-- "examples/sqlalchemy/app/users.py" @@ -48,39 +48,39 @@ Here is a full working example with JWT authentication to help get you started. ## MongoDB -[Open :octicons-link-external-16:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/mongodb) +[Open :material-open-in-new:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/mongodb) -=== ":octicons-file-code-16: requirements.txt" +=== "requirements.txt" ``` --8<-- "examples/mongodb/requirements.txt" ``` -=== ":octicons-file-code-16: main.py" +=== "main.py" ```py --8<-- "examples/mongodb/main.py" ``` -=== ":octicons-file-code-16: app/app.py" +=== "app/app.py" ```py --8<-- "examples/mongodb/app/app.py" ``` -=== ":octicons-file-code-16: app/db.py" +=== "app/db.py" ```py --8<-- "examples/mongodb/app/db.py" ``` -=== ":octicons-file-code-16: app/models.py" +=== "app/models.py" ```py --8<-- "examples/mongodb/app/models.py" ``` -=== ":octicons-file-code-16: app/users.py" +=== "app/users.py" ```py --8<-- "examples/mongodb/app/users.py" @@ -88,39 +88,39 @@ Here is a full working example with JWT authentication to help get you started. ## Tortoise ORM -[Open :octicons-link-external-16:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/tortoise) +[Open :material-open-in-new:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/tortoise) -=== ":octicons-file-code-16: requirements.txt" +=== "requirements.txt" ``` --8<-- "examples/tortoise/requirements.txt" ``` -=== ":octicons-file-code-16: main.py" +=== "main.py" ```py --8<-- "examples/tortoise/main.py" ``` -=== ":octicons-file-code-16: app/app.py" +=== "app/app.py" ```py --8<-- "examples/tortoise/app/app.py" ``` -=== ":octicons-file-code-16: app/db.py" +=== "app/db.py" ```py --8<-- "examples/tortoise/app/db.py" ``` -=== ":octicons-file-code-16: app/models.py" +=== "app/models.py" ```py --8<-- "examples/tortoise/app/models.py" ``` -=== ":octicons-file-code-16: app/users.py" +=== "app/users.py" ```py --8<-- "examples/tortoise/app/users.py" diff --git a/docs/configuration/oauth.md b/docs/configuration/oauth.md index e6ce5bcc..d10f9b98 100644 --- a/docs/configuration/oauth.md +++ b/docs/configuration/oauth.md @@ -123,39 +123,39 @@ app.include_router( #### SQLAlchemy -[Open :octicons-link-external-16:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/sqlalchemy-oauth) +[Open :material-open-in-new:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/sqlalchemy-oauth) -=== ":octicons-file-code-16: requirements.txt" +=== "requirements.txt" ``` --8<-- "examples/sqlalchemy-oauth/requirements.txt" ``` -=== ":octicons-file-code-16: main.py" +=== "main.py" ```py --8<-- "examples/sqlalchemy-oauth/main.py" ``` -=== ":octicons-file-code-16: app/app.py" +=== "app/app.py" ```py --8<-- "examples/sqlalchemy-oauth/app/app.py" ``` -=== ":octicons-file-code-16: app/db.py" +=== "app/db.py" ```py --8<-- "examples/sqlalchemy-oauth/app/db.py" ``` -=== ":octicons-file-code-16: app/models.py" +=== "app/models.py" ```py --8<-- "examples/sqlalchemy-oauth/app/models.py" ``` -=== ":octicons-file-code-16: app/users.py" +=== "app/users.py" ```py --8<-- "examples/sqlalchemy-oauth/app/users.py" @@ -163,39 +163,39 @@ app.include_router( #### MongoDB -[Open :octicons-link-external-16:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/mongodb-oauth) +[Open :material-open-in-new:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/mongodb-oauth) -=== ":octicons-file-code-16: requirements.txt" +=== "requirements.txt" ``` --8<-- "examples/mongodb-oauth/requirements.txt" ``` -=== ":octicons-file-code-16: main.py" +=== "main.py" ```py --8<-- "examples/mongodb-oauth/main.py" ``` -=== ":octicons-file-code-16: app/app.py" +=== "app/app.py" ```py --8<-- "examples/mongodb-oauth/app/app.py" ``` -=== ":octicons-file-code-16: app/db.py" +=== "app/db.py" ```py --8<-- "examples/mongodb-oauth/app/db.py" ``` -=== ":octicons-file-code-16: app/models.py" +=== "app/models.py" ```py --8<-- "examples/mongodb-oauth/app/models.py" ``` -=== ":octicons-file-code-16: app/users.py" +=== "app/users.py" ```py --8<-- "examples/mongodb-oauth/app/users.py" @@ -203,39 +203,39 @@ app.include_router( #### Tortoise ORM -[Open :octicons-link-external-16:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/tortoise-oauth) +[Open :material-open-in-new:](https://github.com/fastapi-users/fastapi-users/tree/master/examples/tortoise-oauth) -=== ":octicons-file-code-16: requirements.txt" +=== "requirements.txt" ``` --8<-- "examples/tortoise-oauth/requirements.txt" ``` -=== ":octicons-file-code-16: main.py" +=== "main.py" ```py --8<-- "examples/tortoise-oauth/main.py" ``` -=== ":octicons-file-code-16: app/app.py" +=== "app/app.py" ```py --8<-- "examples/tortoise-oauth/app/app.py" ``` -=== ":octicons-file-code-16: app/db.py" +=== "app/db.py" ```py --8<-- "examples/tortoise-oauth/app/db.py" ``` -=== ":octicons-file-code-16: app/models.py" +=== "app/models.py" ```py --8<-- "examples/tortoise-oauth/app/models.py" ``` -=== ":octicons-file-code-16: app/users.py" +=== "app/users.py" ```py --8<-- "examples/tortoise-oauth/app/users.py" diff --git a/mkdocs.yml b/mkdocs.yml index 767d5389..64c8ea4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,17 +8,25 @@ theme: primary: 'red' accent: 'red' toggle: - icon: material/lightbulb + icon: material/weather-sunny name: Switch to dark mode - scheme: slate primary: 'red' accent: 'red' toggle: - icon: material/lightbulb-outline + icon: material/weather-night name: Switch to light mode icon: logo: material/account-supervisor favicon: 'favicon.png' + features: + - navigation.instant + - navigation.top + - navigation.sections + - navigation.indexes + - search.suggest + - search.highlight + - content.code.annotate repo_name: frankie567/fastapi-users repo_url: https://github.com/fastapi-users/fastapi-users @@ -28,29 +36,34 @@ markdown_extensions: - toc: permalink: true - admonition - - codehilite + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid - format: !!python/name:mermaid2.fence_mermaid - - pymdownx.tasklist + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tasklist: + custom_checkbox: true - pymdownx.tabbed: alternate_style: true - - pymdownx.snippets - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg + - attr_list + - tables + - def_list plugins: - search - - mermaid2: - arguments: - theme: | - ^(JSON.parse(window.localStorage.getItem('/.__palette')).index == 1) ? 'dark' : 'light' + - mike -extra_javascript: - - https://unpkg.com/mermaid/dist/mermaid.min.js +extra: + version: + provider: mike nav: - About: index.md diff --git a/pyproject.toml b/pyproject.toml index b5602c5a..1e10b09c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,6 +86,7 @@ dev = [ "isort", "pytest-asyncio", "flake8-docstrings", + "mike", "mkdocs", "mkdocs-material", "mkdocs-mermaid2-plugin", From b98ab0bf6646a0dde1b5664b2276e301312aeb1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:33:20 +0200 Subject: [PATCH 2/8] Fix doc CI --- .github/workflows/documentation.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 9dbcc2b8..84bcae7e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -2,6 +2,8 @@ name: Update documentation on: push: + tags: + - "*" branches: - master @@ -22,10 +24,14 @@ jobs: flit install --deps develop --extras oauth,redis - name: Build run: mkdocs build + - name: Parse tag + id: version_tag + uses: battila7/get-version-action@v2 - name: Get tag run: | - python -c "from packaging import version; from fastapi_users import __version__; version = version.parse(__version__); print(f'DOCS_VERSION={version.major}.{version.minor}')" >> $GITHUB_ENV + echo ${{ steps.version_tag.outputs.version }} + echo ${{ github.ref_name }} - name: Deploy run: | git fetch origin gh-pages --depth=1 - mike deploy --push --update-aliases ${{ env.DOCS_VERSION }} latest + mike deploy --push --update-aliases ${{ steps.version_tag.outputs.major }} latest From 37d44ba3e10e5cc248850a180ca872dec043b306 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:35:38 +0200 Subject: [PATCH 3/8] Fix CI doc --- .github/workflows/documentation.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 84bcae7e..c81af1f1 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -30,6 +30,8 @@ jobs: - name: Get tag run: | echo ${{ steps.version_tag.outputs.version }} + echo ${{ steps.version_tag.outputs.major }} + echo ${{ steps.version_tag.outputs.minor }} echo ${{ github.ref_name }} - name: Deploy run: | From 9304ac0223b0e648bf523b78b8dbb55114a49972 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:42:16 +0200 Subject: [PATCH 4/8] Fix CI doc --- .github/workflows/documentation.yml | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index c81af1f1..3b51fc54 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -27,13 +27,9 @@ jobs: - name: Parse tag id: version_tag uses: battila7/get-version-action@v2 - - name: Get tag - run: | - echo ${{ steps.version_tag.outputs.version }} - echo ${{ steps.version_tag.outputs.major }} - echo ${{ steps.version_tag.outputs.minor }} - echo ${{ github.ref_name }} - name: Deploy + env: + DOC_TAG: ${{ steps.version_tag.outputs.version && format('{0}.{1}', steps.version_tag.outputs.major, steps.version_tag.outputs.minor) || 'dev' }} run: | git fetch origin gh-pages --depth=1 - mike deploy --push --update-aliases ${{ steps.version_tag.outputs.major }} latest + mike deploy --push --update-aliases ${{ env.DOC_TAG }} latest From bcc467791a61ca7e2bbcabca20e11d4ff427a82d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:44:10 +0200 Subject: [PATCH 5/8] Fix CI doc --- .github/workflows/documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 3b51fc54..1c744061 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -29,7 +29,7 @@ jobs: uses: battila7/get-version-action@v2 - name: Deploy env: - DOC_TAG: ${{ steps.version_tag.outputs.version && format('{0}.{1}', steps.version_tag.outputs.major, steps.version_tag.outputs.minor) || 'dev' }} + DOC_TAG: ${{ steps.version_tag.outputs.major && steps.version_tag.outputs.minor && format('{0}.{1}', steps.version_tag.outputs.major, steps.version_tag.outputs.minor) || 'dev' }} run: | git fetch origin gh-pages --depth=1 mike deploy --push --update-aliases ${{ env.DOC_TAG }} latest From dc4f73f81f627c3a2a0618561828391b5b30fd9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:46:31 +0200 Subject: [PATCH 6/8] Fix CI doc --- .github/workflows/documentation.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 1c744061..74a4078e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -29,7 +29,9 @@ jobs: uses: battila7/get-version-action@v2 - name: Deploy env: - DOC_TAG: ${{ steps.version_tag.outputs.major && steps.version_tag.outputs.minor && format('{0}.{1}', steps.version_tag.outputs.major, steps.version_tag.outputs.minor) || 'dev' }} + DOC_TAG: ${{ steps.version_tag.outputs.major && steps.version_tag.outputs.minor && format('{0}.{1} latest', steps.version_tag.outputs.major, steps.version_tag.outputs.minor) || 'dev' }} run: | + git config user.name fastapi-users-ci + git config user.email fastapi-users-ci@francoisvoron.com git fetch origin gh-pages --depth=1 - mike deploy --push --update-aliases ${{ env.DOC_TAG }} latest + mike deploy --push --update-aliases ${{ env.DOC_TAG }} From 60e951edc77aedc0bf92de287d77a033d416d026 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 10:54:28 +0200 Subject: [PATCH 7/8] Add outdated warning in docs --- docs-overrides/outdated.html | 8 ++++++++ mkdocs.yml | 1 + 2 files changed, 9 insertions(+) create mode 100644 docs-overrides/outdated.html diff --git a/docs-overrides/outdated.html b/docs-overrides/outdated.html new file mode 100644 index 00000000..0af326af --- /dev/null +++ b/docs-overrides/outdated.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} diff --git a/mkdocs.yml b/mkdocs.yml index 64c8ea4c..81fe714d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,6 +3,7 @@ site_description: Ready-to-use and customizable users management for FastAPI theme: name: 'material' + custom_dir: docs-overrides palette: - scheme: default primary: 'red' From d0456e9499edaabf8acb990ea43eb46b32db4bbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Voron?= Date: Wed, 4 May 2022 11:01:58 +0200 Subject: [PATCH 8/8] Fix doc outdated panel --- docs-overrides/{outdated.html => main.html} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs-overrides/{outdated.html => main.html} (100%) diff --git a/docs-overrides/outdated.html b/docs-overrides/main.html similarity index 100% rename from docs-overrides/outdated.html rename to docs-overrides/main.html