From 90846a23baaea9158bbbe08e4b000937f1b3097a Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sun, 22 Jan 2023 19:16:34 +0800 Subject: [PATCH 1/7] chore: use precommit in dev `environment-dev.yml` is too bloated, for one: most formatting/linting tools should be controlled by `pre-commit` (which sets up its own isolated environments for each tool). Two exceptions: - `black`: since the vscode container uses the black binary to format on save - `isort`: this isn't in pre-commit config yet, to be fixed in the future --- .pre-commit-config.yaml | 5 +++++ Makefile | 4 ++-- environment-dev.yml | 8 +------- mkdocs/devguide.md | 4 ++-- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 24d6bea57..54c8a60c1 100644 --- a/.pre-commit-config.yaml +++ b/.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: diff --git a/Makefile b/Makefile index 603f18348..674a9c436 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ release: format: @echo "Applying Black Python code formatting..." - black -l 79 . + pre-commit run black --all-files test: @echo "Running test suite..." @@ -24,7 +24,7 @@ test: lint: @echo "Checking code formatting..." - flake8 . --exclude "./nbconvert_config.py, ./env, ./venv ./build" + pre-commit run flake8 --all-files docs: @echo "Building documentation..." diff --git a/environment-dev.yml b/environment-dev.yml index 5cd7fc2ad..34ab60516 100644 --- a/environment-dev.yml +++ b/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 diff --git a/mkdocs/devguide.md b/mkdocs/devguide.md index ca3c95f3c..13cd0b909 100644 --- a/mkdocs/devguide.md +++ b/mkdocs/devguide.md @@ -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. From 95337b6c1c48f145f9c4683c3d7d4444e4dfa4bb Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sun, 22 Jan 2023 19:19:08 +0800 Subject: [PATCH 2/7] chore: mkdocs-material compatibility We are now using v0.9 mkdocs-material and mkdocs v1.4, along with it comes several compatibility changes. https://squidfunk.github.io/mkdocs-material/upgrade/ for CHANGELOG E.g. the `watch` option is recommended to use the global mkdocs one. `pymdownx` navigation extension names were wrong... --- mkdocs.yml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 590660a4a..cef0ef31b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,7 @@ site_name: pyjanitor documentation site_url: https://pyjanitor-devs.github.io/pyjanitor +watch: + - janitor/ docs_dir: mkdocs/ @@ -11,8 +13,8 @@ theme: icon: logo: "fontawesome/solid/book" features: - - instant - # - tabs + - navigation.instant + # - navigation.tabs language: en # We customize the navigation by hand to control the order @@ -49,8 +51,6 @@ plugins: selection: docstring_style: restructured-text # custom_templates: templates - watch: - - janitor/ # - mknotebooks: # execute: true # write_markdown: true @@ -67,11 +67,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 From d141e858d9a4d8c6b2a857317018164ef81eede3 Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sun, 22 Jan 2023 21:50:56 +0800 Subject: [PATCH 3/7] feat: add more mkdocs features --- mkdocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index cef0ef31b..c2676fdd4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,6 +15,9 @@ theme: features: - navigation.instant # - navigation.tabs + - navigation.top + - toc.follow + - content.code.copy language: en # We customize the navigation by hand to control the order From 0854961f8f9b1bbef31b274985f7efe6d0d25cf2 Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sun, 22 Jan 2023 21:51:13 +0800 Subject: [PATCH 4/7] docs: update readme --- mkdocs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs/index.md b/mkdocs/index.md index e491f6dff..1bf5b26eb 100644 --- a/mkdocs/index.md +++ b/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? From 3417f3e77b8e43b8050cd2afd3c3fa8b13894690 Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sun, 22 Jan 2023 21:57:32 +0800 Subject: [PATCH 5/7] docs: move development guide to after API ref --- mkdocs.yml | 2 +- mkdocs/devguide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index c2676fdd4..0a347a199 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,7 +24,6 @@ theme: # in which pages show up. nav: - Home: index.md - - Development Guide: devguide.md - API Reference: - Functions: api/functions.md - Biology: api/biology.md @@ -38,6 +37,7 @@ nav: - Timeseries: api/timeseries.md - Utils: api/utils.md - XArray: api/xarray.md + - Development Guide: devguide.md - Changelog: CHANGELOG.md - Authors: AUTHORS.md diff --git a/mkdocs/devguide.md b/mkdocs/devguide.md index 13cd0b909..c9c2c6d6a 100644 --- a/mkdocs/devguide.md +++ b/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 `__ 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. From 9d70af2c183f51a527579227e5ef2f59f48954cc Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sun, 22 Jan 2023 23:26:34 +0800 Subject: [PATCH 6/7] docs: update changelog --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9012e3e7e..614e8543d 100644 --- a/CHANGELOG.md +++ b/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 ## [v0.24.0] - 2022-11-12 From 6644d789ac99ece7b0ccb1044f2da145d5c9bd25 Mon Sep 17 00:00:00 2001 From: Jeremy Goh Date: Sat, 28 Jan 2023 21:13:42 +0800 Subject: [PATCH 7/7] feat: add icon for search bar --- mkdocs/css/apidocs.css | 50 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 9 deletions(-) diff --git a/mkdocs/css/apidocs.css b/mkdocs/css/apidocs.css index f21e19e5f..9ed7dd405 100644 --- a/mkdocs/css/apidocs.css +++ b/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: "/"; +}