[INF] update some mkdocs infrastructure (#1231)

Author: thatlittleboy

.pre-commit-config.yaml

@@ -13,6 +13,11 @@ repos:
   hooks:
   - id: black
     args: [--config, pyproject.toml]
+# - repo: https://github.com/pycqa/isort
+#   rev: 5.11.2
+#   hooks:
+#     - id: isort
+#       name: isort (python)
 - repo: https://github.com/econchick/interrogate
   rev: 1.5.0
   hooks:

CHANGELOG.md

@@ -4,8 +4,9 @@
 
 -   [INF] Replace `pytest.ini` file with `pyproject.toml` file. PR #1204 @Zeroto521
 -   [INF] Extract docstrings tests from all tests. PR #1205 @Zeroto521
--   [BUG] address the `TypeError` when importing v0.24.0 (issue #1201 @xujiboy and @joranbeasley)
+-   [BUG] Address the `TypeError` when importing v0.24.0 (issue #1201 @xujiboy and @joranbeasley)
 -   [INF] Fixed issue with missing PyPI README. PR #1216 @thatlittleboy
+-   [INF] Update some `mkdocs` compatibility code. PR #1231 @thatlittleboy
 -   [DEPR] Add deprecation warnings for `process_text`, `rename_column`, `rename_columns`, `filter_on`, `remove_columns`, `fill_direction`. #1045 @samukweku
 -   [ENH] `pivot_longer` now supports named groups where `names_pattern` is a regular expression. A dictionary can now be passed to `names_pattern`, and is internally evaluated as a list/tuple of regular expressions. Issue #1209 @samukweku
 -   [ENH] Add `summarize` function. Issue #1225 @samukweku

Makefile

@@ -16,15 +16,15 @@ release:
 
 format:
 	@echo "Applying Black Python code formatting..."
-	black -l 79 .
+	pre-commit run black --all-files
 
 test:
 	@echo "Running test suite..."
 	pytest -v -n auto --color=yes
 
 lint:
 	@echo "Checking code formatting..."
-	flake8 . --exclude "./nbconvert_config.py, ./env, ./venv ./build"
+	pre-commit run flake8 --all-files
 
 docs:
 	@echo "Building documentation..."

environment-dev.yml

@@ -4,15 +4,11 @@ channels:
 dependencies:
   - python=3.9
   - biopython
-  - black=22.1.0
+  - black=22.12.0 # keep this in sync with `.pre-commit-config.yaml`
   - bump2version=1.0.1
   - cairo
   - conda
-  - darglint
-  - doc8
-  - flake8
   - hypothesis
-  - interrogate
   - ipykernel
   - ipython
   - isort
@@ -38,8 +34,6 @@ dependencies:
   - pipreqs
   - pip-tools
   - pre-commit
-  - pyflakes
-  - pylint
   - pyspark>=3.2.0
   - pytest
   - pytest-cov

mkdocs.yml

@@ -1,5 +1,7 @@
 site_name: pyjanitor documentation
 site_url: https://pyjanitor-devs.github.io/pyjanitor
+watch:
+  - janitor/
 
 docs_dir: mkdocs/
 
@@ -11,15 +13,17 @@ theme:
   icon:
     logo: "fontawesome/solid/book"
   features:
-    - instant
-    # - tabs
+    - navigation.instant
+    # - navigation.tabs
+    - navigation.top
+    - toc.follow
+    - content.code.copy
   language: en
 
 # We customize the navigation by hand to control the order
 # in which pages show up.
 nav:
   - Home: index.md
-  - Development Guide: devguide.md
   - API Reference:
       - Functions: api/functions.md
       - Biology: api/biology.md
@@ -32,6 +36,7 @@ nav:
       # - PySpark: api/pyspark.md  # will be added back later
       - Timeseries: api/timeseries.md
       - XArray: api/xarray.md
+  - Development Guide: devguide.md
   - Changelog: CHANGELOG.md
   - Authors: AUTHORS.md
 
@@ -48,8 +53,6 @@ plugins:
           selection:
             docstring_style: restructured-text
       # custom_templates: templates
-      watch:
-        - janitor/
 # - mknotebooks:
 #     execute: true
 #     write_markdown: true
@@ -66,11 +69,9 @@ markdown_extensions:
   - pymdownx.highlight:
       use_pygments: false
   - pymdownx.inlinehilite
-  # - pymdownx.tabbed
-  # - pymdownx.arithmatex
-  # - pymdownx.details
-  # - pymdownx.superfences
-  # - markdown.extensions.attr_list
+  # - pymdownx.tabbed:
+  #     alternate_style: true
+  - pymdownx.superfences
 
 extra_javascript:
   - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML

mkdocs/css/apidocs.css

@@ -1,14 +1,46 @@
 /* https://mkdocstrings.github.io/theming/#css-classes */
-.doc-property { border-radius: 15px; padding: 0 5px; }
-.doc-property-special { background-color: blue; color: white; }
-.doc-property-private { background-color: red; color: white; }
-.doc-property-property { background-color: green; color: white; }
-.doc-property-read-only { background-color: yellow; color: black; }
+.doc-property {
+  border-radius: 15px;
+  padding: 0 5px;
+}
+.doc-property-special {
+  background-color: blue;
+  color: white;
+}
+.doc-property-private {
+  background-color: red;
+  color: white;
+}
+.doc-property-property {
+  background-color: green;
+  color: white;
+}
+.doc-property-read-only {
+  background-color: yellow;
+  color: black;
+}
 
 /* https://mkdocstrings.github.io/handlers/python/#recommended-style-material */
 /* Indentation. */
 div.doc-contents:not(.first) {
-    padding-left: 25px;
-    border-left: 4px solid rgba(230, 230, 230);
-    margin-bottom: 80px;
-  }
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+  margin-bottom: 80px;
+}
+
+/* add a keyboard shortcut icon for search bar,
+ * https://github.com/squidfunk/mkdocs-material/issues/2574#issuecomment-821979698
+ */
+[data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after {
+  position: absolute;
+  top: 0.3rem;
+  right: 0.3rem;
+  display: block;
+  padding: 0.1rem 0.4rem;
+  color: var(--md-default-bg-color--lighter);
+  font-weight: bold;
+  font-size: 0.8rem;
+  border: 0.05rem solid var(--md-default-bg-color--lighter);
+  border-radius: 0.1rem;
+  content: "/";
+}

mkdocs/devguide.md

@@ -87,7 +87,7 @@ selecting the correct kernel from the top right corner of JupyterLab!
     For PyCharm users,
     here are some `instructions <PYCHARM_USERS.html>`__  to get your Conda environment set up.
 
-### Install the pre-commit hooks.
+### Install the pre-commit hooks
 
 `pre-commit` hooks are available
 to run code formatting checks automagically before git commits happen.
@@ -172,8 +172,8 @@ formatted and that all tests still pass.
 
 To do so:
 
-* Run `python -m flake8 --exclude nbconvert_config.py janitor` to check code styling problems
-* Run `python -m black -c pyproject.toml` to format your code.
+* Run `make lint` to check code styling problems.
+* Run `make format` to format your code.
 * Run `python -m interrogate -c pyproject.toml` to check your code for missing docstring.
 * Run `darglint -v 2` to check quality of your docstrings.
 * Run `python -m pytest` to run all unit tests.

mkdocs/index.md

@@ -10,8 +10,8 @@ provides a clean API for cleaning data.
 
 ## Quick start
 
-- Installation: `conda install -c conda-forge pyjanitor`
-- Check out the collection of [general functions](https://pyjanitor-devs.github.io/pyjanitor/api/functions/)
+- Installation: `conda install -c conda-forge pyjanitor`. Read more installation instructions [here](https://pyjanitor-devs.github.io/pyjanitor/#installation).
+- Check out the collection of [general functions](https://pyjanitor-devs.github.io/pyjanitor/api/functions/).
 
 ## Why janitor?