From 38b7186682e0ea7aab250b20cf6a47cafa7deb49 Mon Sep 17 00:00:00 2001 From: yfprojects <62463991+real-yfprojects@users.noreply.github.com> Date: Mon, 24 Jul 2023 06:41:04 +0000 Subject: [PATCH] Make `docs/index.md` a symlink. (#53) Co-authored-by: real-yfprojects --- .pre-commit-config.yaml | 8 -- .pre_commit_helper_scripts/copy_readme.py | 7 -- docs/index.md | 140 +--------------------- 3 files changed, 1 insertion(+), 154 deletions(-) delete mode 100644 .pre_commit_helper_scripts/copy_readme.py mode change 100644 => 120000 docs/index.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 57f1009..e21e5a3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -29,11 +29,3 @@ repos: rev: 0.0.4 hooks: - id: markdown-toc-creator - - - repo: local - hooks: - - id: copy_readme - name: copy_readme - entry: python .pre_commit_helper_scripts/copy_readme.py - language: system - types: [python] diff --git a/.pre_commit_helper_scripts/copy_readme.py b/.pre_commit_helper_scripts/copy_readme.py deleted file mode 100644 index 2df723a..0000000 --- a/.pre_commit_helper_scripts/copy_readme.py +++ /dev/null @@ -1,7 +0,0 @@ -"""Copy `README.md` into `docs/index.md` at every pre-commit runs""" - -with open('README.md', encoding='UTF-8') as fp: - lines = fp.readlines() - -with open('docs/index.md', 'w', encoding='UTF-8') as fp: - fp.writelines(lines) diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 1110353..0000000 --- a/docs/index.md +++ /dev/null @@ -1,139 +0,0 @@ -# pydoclint - -A Python docstring linter to check whether a docstring's sections (arguments, -returns, raises, ...) match the function signature or function implementation. - -It runs really fast. In fact, it can be thousands of times faster than -[darglint](https://github.com/terrencepreilly/darglint) (or its maintained fork -[darglint2](https://github.com/akaihola/darglint2)). - -Here is a comparison of linting time on some famous Python projects: - -| | pydoclint | darglint | -| ------------------------------------------------------------ | --------- | --------------------------------- | -| [numpy](https://github.com/numpy/numpy) | 2.0 sec | 49 min 9 sec (1,475x slower) | -| [scikit-learn](https://github.com/scikit-learn/scikit-learn) | 2.4 sec | 3 hr 5 min 33 sec (4,639x slower) | - -Additionally, _pydoclint_ can detect some quite a few style violations that -darglint cannot. - -Currently, _pydoclint_ supports three docstring styles: - -- The [numpy stlyle](https://numpydoc.readthedocs.io/en/latest/format.html) -- The - [Google style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html) -- The - [Sphinx style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) - -Another note: this linter and [pydocstyle](https://github.com/PyCQA/pydocstyle) -serves complementary purposes. It is recommended that you use both together. - ---- - -**Table of Contents** - - - -- [1. Installation](#1-installation) -- [2. Usage](#2-usage) - - [2.1. As a native command line tool](#21-as-a-native-command-line-tool) - - [2.2. As a _flake8_ plugin](#22-as-a-flake8-plugin) - - [2.3. As a pre-commit hook](#23-as-a-pre-commit-hook) - - [2.4. Native vs _flake8_](#24-native-vs-flake8) - - [2.5. How to configure _pydoclint_](#25-how-to-configure-pydoclint) -- [3. Style violation codes](#3-style-violation-codes) -- [4. Notes for users](#4-notes-for-users) -- [5. Notes for developers](#5-notes-for-developers) - - - -## 1. Installation - -``` -pip install pydoclint -``` - -Note that _pydoclint_ currently only supports Python 3.8 and above. (Python 3.7 -support may be added if there are interests and requests.) - -## 2. Usage - -### 2.1. As a native command line tool - -``` -pydoclint -``` - -Replace `` with the file/folder names you want, such as `.`. - -### 2.2. As a _flake8_ plugin - -Once you install _pydoclint_ you will have also installed _flake8_. Then you -can run: - -``` -flake8 --select=DOC -``` - -If you don't include `--select=DOC` in your command, _flake8_ will also run -other built-in _flake8_ linters on your code. - -### 2.3. As a pre-commit hook - -_pydoclint_ is configured for [pre-commit](https://pre-commit.com/) and can be -set up as a hook with the following `.pre-commit-config.yaml` configuration: - -```yaml -- repo: https://github.com/jsh9/pydoclint - rev: - hooks: - - id: pydoclint - args: - - "--config=pyproject.toml" -``` - -You will need to install `pre-commit` and run `pre-commit install`. - -### 2.4. Native vs _flake8_ - -Should I use _pydoclint_ as a native command line tool or a _flake8_ plugin? -Here's comparison: - -| | Pros | Cons | -| --------------- | ---------------------------------------- | ------------------------------------------------------------- | -| Native tool | Slightly faster | No inline or project-wide omission support right now [*] | -| _flake8_ plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together | - -\*) This feature may be added in the near future - -### 2.5. How to configure _pydoclint_ - -Please read this page: -[How to configure _pydoclint_](https://jsh9.github.io/pydoclint/how_to_config.html) - -## 3. Style violation codes - -_pydoclint_ currently has 6 categories of style violation codes: - -- `DOC0xx`: Docstring parsing issues -- `DOC1xx`: Violations about input arguments -- `DOC2xx`: Violations about return argument(s) -- `DOC3xx`: Violations about class docstring and class constructor -- `DOC4xx`: Violations about "yield" statements -- `DOC5xx`: Violations about "raise" statements - -For detailed explanations of each violation code, please read this page: -[_pydoclint_ style violation codes](https://jsh9.github.io/pydoclint/violation_codes.html). - -## 4. Notes for users - -If you'd like to use _pydoclint_ for your project, it is recommended that you -read these additional notes -[here](https://jsh9.github.io/pydoclint/notes_for_users.html). - -## 5. Notes for developers - -If you'd like to contribute to the code base of _pydoclint_, thank you! - -[This guide](https://jsh9.github.io/pydoclint/notes_for_developers.html) can -hopefully help you get familiar with the code base faster. diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 0000000..42061c0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +README.md \ No newline at end of file