From e021359e7097f35d8ce21229ee383d5715284c78 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Wed, 17 Apr 2024 09:57:47 +0200 Subject: [PATCH 1/2] Switch to Furo docs theme --- docs/source/conf.py | 8 +++++++- requirements/requirements-docs.in | 4 ++-- requirements/requirements-docs.txt | 21 +++++++++++++-------- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2fcb39e..b400d78 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,5 +55,11 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "sphinx_rtd_theme" +html_theme = "furo" html_static_path = ["_static"] + +html_theme_options = { + "source_repository": "https://github.com/Viicos/jsonlogic/", + "source_branch": "main", + "source_directory": "docs/source/", +} diff --git a/requirements/requirements-docs.in b/requirements/requirements-docs.in index 25597cd..33c4ed4 100644 --- a/requirements/requirements-docs.in +++ b/requirements/requirements-docs.in @@ -1,4 +1,4 @@ -c requirements.txt +furo sphinx -sphinx-rtd-theme -sphinx-paramlinks +sphinx-paramlinks \ No newline at end of file diff --git a/requirements/requirements-docs.txt b/requirements/requirements-docs.txt index b230238..7e44045 100644 --- a/requirements/requirements-docs.txt +++ b/requirements/requirements-docs.txt @@ -8,6 +8,8 @@ alabaster==0.7.16 # via sphinx babel==2.14.0 # via sphinx +beautifulsoup4==4.12.3 + # via furo certifi==2024.2.2 # via requests charset-normalizer==3.3.2 @@ -16,7 +18,8 @@ docutils==0.20.1 # via # sphinx # sphinx-paramlinks - # sphinx-rtd-theme +furo==2024.1.29 + # via -r requirements/requirements-docs.in idna==3.6 # via requests imagesize==1.4.1 @@ -28,29 +31,31 @@ markupsafe==2.1.5 packaging==24.0 # via sphinx pygments==2.17.2 - # via sphinx + # via + # furo + # sphinx requests==2.31.0 # via sphinx snowballstemmer==2.2.0 # via sphinx +soupsieve==2.5 + # via beautifulsoup4 sphinx==7.2.6 # via # -r requirements/requirements-docs.in + # furo + # sphinx-basic-ng # sphinx-paramlinks - # sphinx-rtd-theme - # sphinxcontrib-jquery +sphinx-basic-ng==1.0.0b2 + # via furo sphinx-paramlinks==0.6.0 # via -r requirements/requirements-docs.in -sphinx-rtd-theme==2.0.0 - # via -r requirements/requirements-docs.in sphinxcontrib-applehelp==1.0.8 # via sphinx sphinxcontrib-devhelp==1.0.6 # via sphinx sphinxcontrib-htmlhelp==2.0.5 # via sphinx -sphinxcontrib-jquery==4.1 - # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx sphinxcontrib-qthelp==1.0.7 From f93e2f5a318ac9fbc1c4c3bad9a0b9381cf73b69 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Wed, 17 Apr 2024 20:18:01 +0200 Subject: [PATCH 2/2] Check docs in CI --- .github/workflows/tests.yml | 25 ++++++++++++++++++++++++ docs/source/_static/.gitkeep | 0 docs/source/conf.py | 2 ++ docs/source/usage/creating_operators.rst | 2 +- requirements/requirements-docs.in | 3 ++- requirements/requirements-docs.txt | 10 ++++++++-- 6 files changed, 38 insertions(+), 4 deletions(-) create mode 100644 docs/source/_static/.gitkeep diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index f71b656..060d4e1 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -22,3 +22,28 @@ jobs: pip-sync requirements/requirements.txt requirements/requirements-test.txt - name: Test with tox run: tox + + docs: + name: Build and check documentation + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: Install dependencies + run: | + pip install pip-tools + pip-sync requirements/requirements.txt requirements/requirements-docs.txt + - name: Lint docs with sphinx-lint + run: | + sphinx-lint docs + - name: Build docs and check the integrity of external links + run: | + ls source + sphinx-build --builder linkcheck --fail-on-warning "source" "build" + sphinx-build --builder html --fail-on-warning "source" "build" + working-directory: + ./docs diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/conf.py b/docs/source/conf.py index b400d78..af5a581 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,6 +52,8 @@ "python": ("https://docs.python.org/3", None), } +linkcheck_retries = 3 + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/docs/source/usage/creating_operators.rst b/docs/source/usage/creating_operators.rst index 9a38e52..1fad27d 100644 --- a/docs/source/usage/creating_operators.rst +++ b/docs/source/usage/creating_operators.rst @@ -114,4 +114,4 @@ operator. .. [#f1] You could implement some checks on the type of the provided argument, if it happens to be a :data:`~jsonlogic.typing.JSONLogicPrimitive` where the ``>`` argument doesn't make sense (arrays for instance). However, this is a - task better suited for typechecking. \ No newline at end of file + task better suited for typechecking. diff --git a/requirements/requirements-docs.in b/requirements/requirements-docs.in index 33c4ed4..285a486 100644 --- a/requirements/requirements-docs.in +++ b/requirements/requirements-docs.in @@ -1,4 +1,5 @@ -c requirements.txt furo sphinx -sphinx-paramlinks \ No newline at end of file +sphinx-lint +sphinx-paramlinks diff --git a/requirements/requirements-docs.txt b/requirements/requirements-docs.txt index 7e44045..778ec9b 100644 --- a/requirements/requirements-docs.txt +++ b/requirements/requirements-docs.txt @@ -14,7 +14,7 @@ certifi==2024.2.2 # via requests charset-normalizer==3.3.2 # via requests -docutils==0.20.1 +docutils==0.21.1 # via # sphinx # sphinx-paramlinks @@ -30,17 +30,21 @@ markupsafe==2.1.5 # via jinja2 packaging==24.0 # via sphinx +polib==1.2.0 + # via sphinx-lint pygments==2.17.2 # via # furo # sphinx +regex==2024.4.16 + # via sphinx-lint requests==2.31.0 # via sphinx snowballstemmer==2.2.0 # via sphinx soupsieve==2.5 # via beautifulsoup4 -sphinx==7.2.6 +sphinx==7.3.5 # via # -r requirements/requirements-docs.in # furo @@ -48,6 +52,8 @@ sphinx==7.2.6 # sphinx-paramlinks sphinx-basic-ng==1.0.0b2 # via furo +sphinx-lint==0.9.1 + # via -r requirements/requirements-docs.in sphinx-paramlinks==0.6.0 # via -r requirements/requirements-docs.in sphinxcontrib-applehelp==1.0.8