From 2dc91b754ecc499f76d17c5c38dd71cc718e5036 Mon Sep 17 00:00:00 2001 From: Eric Ma Date: Sun, 14 Aug 2022 20:54:42 +0000 Subject: [PATCH 1/5] HOTFIX documentation bugfix by pinning mkdocstrings to 0.18.1 --- environment-dev.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/environment-dev.yml b/environment-dev.yml index b2ff0c6f8..f9c36d1be 100644 --- a/environment-dev.yml +++ b/environment-dev.yml @@ -22,7 +22,7 @@ dependencies: - make - mkdocs - mkdocs-material - - mkdocstrings-python + - mkdocstrings=0.18.1 - missingno - multipledispatch - mypy From 4fac4936ed9ea5b8c226241c2bf2ff7f9cdf0f0f Mon Sep 17 00:00:00 2001 From: Eric Ma Date: Mon, 15 Aug 2022 00:35:10 +0000 Subject: [PATCH 2/5] Add mkdocstrings-python-legacy into env --- environment-dev.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/environment-dev.yml b/environment-dev.yml index f9c36d1be..4f26797fb 100644 --- a/environment-dev.yml +++ b/environment-dev.yml @@ -23,6 +23,7 @@ dependencies: - mkdocs - mkdocs-material - mkdocstrings=0.18.1 + - mkdocstrings-python-legacy=0.2.2 - missingno - multipledispatch - mypy From 68fa82f0828e34f24d1a705c1723e303ee96d44a Mon Sep 17 00:00:00 2001 From: Zero Date: Mon, 15 Aug 2022 08:57:31 +0800 Subject: [PATCH 3/5] Apply to mkdocs/environment --- mkdocs/environment.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/mkdocs/environment.yaml b/mkdocs/environment.yaml index 376256700..2659bf9b2 100644 --- a/mkdocs/environment.yaml +++ b/mkdocs/environment.yaml @@ -20,4 +20,7 @@ dependencies: # doc - mkdocs - mkdocs-material - - mkdocstrings-python + # To fix #1146 + # - mkdocstrings-python + - mkdocstrings=0.18.1 + - mkdocstrings-python-legacy=0.2.2 From fe1227c1779a855741609ee834c25bfe590b253c Mon Sep 17 00:00:00 2001 From: Eric Ma Date: Mon, 15 Aug 2022 01:19:52 +0000 Subject: [PATCH 4/5] Add first pass on automated test for docs build. --- .github/workflows/docs-preview.yml | 2 +- mkdocs.yml | 2 +- tests/test_documentation_build.py | 24 ++++++++++++++++++++++++ 3 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 tests/test_documentation_build.py diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index 590451750..ffe374d12 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -22,7 +22,7 @@ jobs: with: auto-update-conda: true miniforge-variant: Mambaforge - environment-file: mkdocs/environment.yaml + environment-file: environment-dev.yml use-mamba: true - name: Build docs diff --git a/mkdocs.yml b/mkdocs.yml index 7d0c2dc63..3c95832c1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,7 +46,7 @@ plugins: show_source: true # https://github.com/mkdocstrings/mkdocstrings/issues/278#issuecomment-831411193 selection: - docstring_style: sphinx + docstring_style: restructured-text # custom_templates: templates watch: - janitor/ diff --git a/tests/test_documentation_build.py b/tests/test_documentation_build.py new file mode 100644 index 000000000..174c47777 --- /dev/null +++ b/tests/test_documentation_build.py @@ -0,0 +1,24 @@ +"""Tests for documentation build.""" + +import os + + +def test_docs_general_functions_present(): + """Test that all docs pages build correctly. + + TODO: There has to be a better way to automatically check that + all of the functions are present in the docs. + This is an awesome thing that we could use help with in the future. + """ + # Build docs using mkdocs + os.system("mkdocs build --clean") + + # We want to check that the following keywords are all present. + # I put in a subsample of general functions. + # This can be made much more robust. + rendered_correctly = False + with open("./site/api/functions/index.html", "r+") as f: + for line in f.readlines(): + if "add_columns" in line or "update_where" in line: + rendered_correctly = True + assert rendered_correctly From 6cf4762272c341602329711e49369c67ddca69cd Mon Sep 17 00:00:00 2001 From: Eric Ma Date: Mon, 15 Aug 2022 01:21:03 +0000 Subject: [PATCH 5/5] Commented out `mkdocs/environment.yaml` until further discussion. --- mkdocs/environment.yaml | 55 ++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/mkdocs/environment.yaml b/mkdocs/environment.yaml index 2659bf9b2..954cbbb7a 100644 --- a/mkdocs/environment.yaml +++ b/mkdocs/environment.yaml @@ -1,26 +1,29 @@ -name: pyjanitor-doc -channels: - - conda-forge -dependencies: - - python - # required - - pandas - - pandas-flavor - - multipledispatch - - scipy - # optional - - biopython - - natsort - - pyspark>=3.2.0 - - rdkit - - tqdm - - unyt - - xarray - - numba - # doc - - mkdocs - - mkdocs-material - # To fix #1146 - # - mkdocstrings-python - - mkdocstrings=0.18.1 - - mkdocstrings-python-legacy=0.2.2 +# 14 August 2022: Temporarily commenting out. +# See: https://github.com/pyjanitor-devs/pyjanitor/pull/1147#issuecomment-1214508157 +# for more context on why. +# name: pyjanitor-doc +# channels: +# - conda-forge +# dependencies: +# - python +# # required +# - pandas +# - pandas-flavor +# - multipledispatch +# - scipy +# # optional +# - biopython +# - natsort +# - pyspark>=3.2.0 +# - rdkit +# - tqdm +# - unyt +# - xarray +# - numba +# # doc +# - mkdocs +# - mkdocs-material +# # To fix #1146 +# # - mkdocstrings-python +# - mkdocstrings=0.18.1 +# - mkdocstrings-python-legacy=0.2.2