[INF/DOC] Documentation bugfix by pinning mkdocstrings to 0.18.1 (#1147)

* HOTFIX documentation bugfix by pinning mkdocstrings to 0.18.1

* Add mkdocstrings-python-legacy into env

* Apply to mkdocs/environment

* Add first pass on automated test for docs build.

* Commented out `mkdocs/environment.yaml` until further discussion.

Co-authored-by: Zero <Zeroto521@gmail.com>

Author: ericmjl

.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

environment-dev.yml

@@ -22,7 +22,8 @@ dependencies:
   - make
   - mkdocs
   - mkdocs-material
-  - mkdocstrings-python
+  - mkdocstrings=0.18.1
+  - mkdocstrings-python-legacy=0.2.2
   - missingno
   - multipledispatch
   - mypy

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/

mkdocs/environment.yaml

@@ -1,23 +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
-  - mkdocstrings-python
+# 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

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