From 4501b909931030c14a1aa74864cd0e70151b5bda Mon Sep 17 00:00:00 2001 From: "Jose R. Zapata" Date: Fri, 26 Jan 2024 20:41:36 -0500 Subject: [PATCH] Feature/fix_gh_page (#11) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ✨ 📝 add gh-pages badge * ⬆️ upgrade mkdocs-material * 🔧 update mkdocs code configurations * 📝 ✏️ fix links in readme to absolute links --- README.md | 52 +++++++++++++++++++++++++++++----------------------- mkdocs.yml | 8 ++++++++ poetry.lock | 8 ++++---- 3 files changed, 41 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 66cad03..36e8769 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) +[![pages-build-deployment](https://github.com/JoseRZapata/data-science-project-template/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages)](https://github.com/JoseRZapata/data-science-project-template/actions/workflows/pages/pages-build-deployment) Template for a data science projects with software development tools @@ -40,17 +41,23 @@ It is highly recommended to use a python version manager like [Pyenv] and this p 1. [Install Pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) 2. [Install Poetry](https://python-poetry.org/docs/#installation) -Via [Cruft](recommended): +Via [Cruft] - **recommended**: -```shell script +```bash title="install cruft" pip install --user cruft # Install `cruft` on your path for easy access +``` + +```shell title="create project" cruft create https://github.com/JoseRZapata/data-science-project-template ``` Via [Cookiecutter]: -```shell script +```shell title="install cookiecutter" pip install --user cookiecutter # Install `cookiecutter` on your path for easy access +``` + +```shell title="create project" cookiecutter gh:JoseRZapata/data-science-project-template ``` @@ -60,13 +67,13 @@ Note: **_Cookiecutter_** uses `gh:` as short-hand for `https://github.com/` If the project was originally installed via [Cookiecutter], you must first use [Cruft] to link the project with the original template: -```shell script +```shell cruft link https://github.com/JoseRZapata/data-science-project-template ``` Then/else: -```shell script +```shell cruft update ``` @@ -135,7 +142,7 @@ Folder structure for data science projects [why?](https://towardsdatascience.co with [Poetry] - [`why?`](https://mathdatasimplified.com/poetry-a-better-way-to-manage-python-dependencies/) - Project workflow orchestration with [Make] as an [interface shim](https://en.wikipedia.org/wiki/Shim_(computing)) - - Self-documenting [Makefile]({{cookiecutter.repo_name}}/Makefile); just type + - Self-documenting [Makefile](https://github.com/JoseRZapata/data-science-project-template/blob/main/{{cookiecutter.repo_name}}/Makefile); just type `make` on the command line to display auto-generated documentation on available targets: - Automated Cookiecutter template synchronization with [Cruft] - [`why?`](https://careers.wolt.com/en/blog/tech/project-template-for-modern-python-packages) @@ -145,36 +152,36 @@ Folder structure for data science projects [why?](https://towardsdatascience.co #### :seedling: Conditionally Rendered Python Package or Project Boilerplate -- [Optional] [Jupyter](https://jupyter.org/) support +- _Optional:_ [Jupyter] support ### :wrench: Maintainability #### :label: Type Checking and Data Validation -- Static type-checking with [Mypy](http://mypy-lang.org) +- Static type-checking with [Mypy] #### :white_check_mark: Testing/Coverage - Testing with [Pytest] - Doctests - with [`xdoctest`](https://xdoctest.readthedocs.io) + with [xdoctest] - Code coverage - with [Coverage.py](https://coverage.readthedocs.io/) + with [Coverage.py] - Coverage reporting with [Codecov] #### :rotating_light: Linting - Code quality: - - [Ruff](https://github.com/charliermarsh/ruff) + - [Ruff] - A blazing-fast (10x-100x faster) replacement for - [Pylint], [Flake8] (including major plugins) and more linters under a single, common interface + ~~[Pylint]~~, ~~[Flake8]~~ (including major plugins) and more linters under a single, common interface - [ShellCheck](https://github.com/koalaman/shellcheck) - Code formatting: - - [Ruff](https://github.com/charliermarsh/ruff) + - [Ruff] - A blazing-fast (10x-100x faster) replacement for - [Black], [isort], [pyupgrade] and more formaters under a single, common interface + ~~[Black]~~, ~~[isort]~~, ~~[pyupgrade]~~ and more formaters under a single, common interface - General file formatting: - [`end-of-file-fixer`](https://github.com/pre-commit/pre-commit-hooks#end-of-file-fixer) @@ -192,8 +199,8 @@ Folder structure for data science projects [why?](https://towardsdatascience.co #### :construction_worker: CI/CD - Dependency updates - with [Dependabot](https://dependabot.com/) - - Automated [Dependabot](https://dependabot.com/) PR merging + with [Dependabot] + - Automated [Dependabot] PR merging with the [Dependabot Auto Merge GitHub Action](https://github.com/ahmadnassri/action-dependabot-auto-merge) ## :lock: Security @@ -234,11 +241,11 @@ Folder structure for data science projects [why?](https://towardsdatascience.co [Black]: https://github.com/psf/black [Codecov]: https://codecov.io/ [Cookiecutter]:https://cookiecutter.readthedocs.io/stable/ -[coverage.py]: https://coverage.readthedocs.io/ +[Coverage.py]: https://coverage.readthedocs.io/ [Cruft]: https://cruft.github.io/cruft/ -[Data structure]: {{cookiecutter.repo_name}}/data/README.md +[Data structure]: https://github.com/JoseRZapata/data-science-project-template/blob/main/{{cookiecutter.repo_name}}/data/README.md [deepcheck]:https://deepcheck.io/ -[dependabot]: https://github.com/dependabot/dependabot-core +[Dependabot]: https://github.com/dependabot/dependabot-core [depy]:https://fpgmaas.github.io/deptry/ [DVC]:https://dvc.org/ [Flake8]:https://github.com/PyCQA/flake8 @@ -255,23 +262,22 @@ Folder structure for data science projects [why?](https://towardsdatascience.co [MlFlow]:https://www.mlflow.org/ [Mypy]: http://mypy-lang.org/ [myst]: https://myst-parser.readthedocs.io/ -[Notebook template]: {{cookiecutter.repo_name}}/notebooks/notebook_template.ipynb +[Notebook template]: https://github.com/JoseRZapata/data-science-project-template/blob/main/{{cookiecutter.repo_name}}/notebooks/notebook_template.ipynb [NumPy]:https://numpy.org/ [OmegaConf]: https://omegaconf.readthedocs.io/en/latest/ [Pandas]:https://pandas.pydata.org/ [pandera]:(https://pandera.readthedocs.io/en/stable/) [Poetry]: https://python-poetry.org/ [pre-commit]: https://pre-commit.com/ -[Pull Request template]: {{cookiecutter.repo_name}}/.github/pull_request_template.md +[Pull Request template]: https://github.com/JoseRZapata/data-science-project-template/blob/main/{{cookiecutter.repo_name}}/.github/pull_request_template.md [Pyenv]: https://github.com/pyenv/pyenv [Pylint]:https://github.com/PyCQA/pylint [pypi]: https://pypi.org/ [Pytest]: https://docs.pytest.org/en/latest/ [pyupgrade]: https://github.com/asottile/pyupgrade [Ruff]: https://docs.astral.sh/ruff/ -[safety]: https://github.com/pyupio/safety [scikit-learn]:https://scikit-learn.org/ [testpypi]: https://test.pypi.org/ [tox]: https://tox.readthedocs.io/ [typeguard]: https://github.com/agronholm/typeguard -[xdoctest]: https://github.com/Erotemic/xdoctest +[xdoctest]: https://xdoctest.readthedocs.io/en/latest/ diff --git a/mkdocs.yml b/mkdocs.yml index 34f8418..5f6da50 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,8 @@ theme: toggle: icon: material/toggle-switch name: Switch to light mode + features: + - content.code.copy nav: - Introduction: 'index.md' @@ -23,3 +25,9 @@ markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.superfences diff --git a/poetry.lock b/poetry.lock index 49c6745..462b648 100644 --- a/poetry.lock +++ b/poetry.lock @@ -425,13 +425,13 @@ mkdocs = ">=1.1" [[package]] name = "mkdocs-material" -version = "9.5.4" +version = "9.5.5" description = "Documentation that simply works" optional = false python-versions = ">=3.8" files = [ - {file = "mkdocs_material-9.5.4-py3-none-any.whl", hash = "sha256:efd7cc8ae03296d728da9bd38f4db8b07ab61f9738a0cbd0dfaf2a15a50e7343"}, - {file = "mkdocs_material-9.5.4.tar.gz", hash = "sha256:3d196ee67fad16b2df1a458d650a8ac1890294eaae368d26cee71bc24ad41c40"}, + {file = "mkdocs_material-9.5.5-py3-none-any.whl", hash = "sha256:ac50b2431a79a3b160fdefbba37c9132485f1a69166aba115ad49fafdbbbc5df"}, + {file = "mkdocs_material-9.5.5.tar.gz", hash = "sha256:4480d9580faf42fed0123d0465502bfc1c0c239ecc9c4d66159cf0459ea1b4ae"}, ] [package.dependencies] @@ -449,7 +449,7 @@ requests = ">=2.26,<3.0" [package.extras] git = ["mkdocs-git-committers-plugin-2 (>=1.1,<2.0)", "mkdocs-git-revision-date-localized-plugin (>=1.2,<2.0)"] -imaging = ["cairosvg (>=2.6,<3.0)", "pillow (>=9.4,<10.0)"] +imaging = ["cairosvg (>=2.6,<3.0)", "pillow (>=10.2,<11.0)"] recommended = ["mkdocs-minify-plugin (>=0.7,<1.0)", "mkdocs-redirects (>=1.2,<2.0)", "mkdocs-rss-plugin (>=1.6,<2.0)"] [[package]]